Workstations

Workstations are used to view, annotate and upload images to grand challenge. A workstation admin is able to upload a WorkstationImage, which is a docker container image. A WorkstationImage expose a http and, optionally, a websocket port. A workstation user can then launch a workstation Session for a particular WorkstationImage.

When a new session is started, a new container instance of the selected WorkstationImage is lauched on the docker host. The connection to the container will be proxied, and only accessible to the user that created the session. The proxy will map the http and websocket connections from the user to the running instance, which is mapped by the container hostname. The container instance will have the users API token set in the environment, so that it is able to interact with the grand challenge API as this user. The user is able to stop the container, otherwise it will be terminated after maxmium_duration is reached.

class grandchallenge.workstations.models.Feedback(id, created, modified, session, screenshot, user_comment, context)[source]
Parameters:

Relationship fields:

Parameters:

session (ForeignKey to Session) – Session (related name: feedback)

Reverse relationships:

Parameters:

  • feedbackuserobjectpermission (Reverse ForeignKey from FeedbackUserObjectPermission) – All feedback user object permissions of this feedback (related name of content_object)

  • feedbackgroupobjectpermission (Reverse ForeignKey from FeedbackGroupObjectPermission) – All feedback group object permissions of this feedback (related name of content_object)

  • download (Reverse ForeignKey from Download) – All downloads of this feedback (related name of feedback)

exception DoesNotExist
exception MultipleObjectsReturned
save(*args, **kwargs)[source]

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

Return type:

None

class grandchallenge.workstations.models.FeedbackGroupObjectPermission(id, permission, group, content_object)[source]
Parameters:

id (AutoField) – Primary key: ID

Relationship fields:

Parameters:

  • permission (ForeignKey to Permission) – Permission (related name: feedbackgroupobjectpermission)

  • group (ForeignKey to Group) – Group (related name: feedbackgroupobjectpermission)

  • content_object (ForeignKey to Feedback) – Content object (related name: feedbackgroupobjectpermission)

exception DoesNotExist
exception MultipleObjectsReturned
class grandchallenge.workstations.models.FeedbackUserObjectPermission(id, permission, user, content_object)[source]
Parameters:

id (AutoField) – Primary key: ID

Relationship fields:

Parameters:

  • permission (ForeignKey to Permission) – Permission (related name: feedbackuserobjectpermission)

  • user (ForeignKey to User) – User (related name: feedbackuserobjectpermission)

  • content_object (ForeignKey to Feedback) – Content object (related name: feedbackuserobjectpermission)

exception DoesNotExist
exception MultipleObjectsReturned
class grandchallenge.workstations.models.Session(*args, **kwargs)[source]

Tracks who has launched workstation images. The WorkstationImage will be launched as a Service. The Session is responsible for starting and stopping the Service.

Parameters:

  • status – Stores what has happened with the service, is it running, errored, etc?

  • region – Stores which region this session runs in

  • creator – Who created the session? This is also the only user that should be able to access the launched service.

  • workstation_image – The container image that will be launched by this Session.

  • maximum_duration – The maximum time that the service can be active before it is terminated

  • user_finished – Indicates if the user has chosen to end the session early

  • history – The history of this Session

  • id (UUIDField) – Primary key: Id

  • created (DateTimeField) – Created

  • modified (DateTimeField) – Modified

  • logs (TextField) – Logs

  • ping_times (JSONField) – Ping times

  • extra_env_vars (JSONField) – Extra env vars. Extra environment variables to include in this session

Relationship fields:

Parameters:

auth_token (ForeignKey to AuthToken) – Auth token (related name: session)

Reverse relationships:

Parameters:
exception DoesNotExist
exception MultipleObjectsReturned
class Region(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
property environment: dict
Returns:

The environment variables that should be set on the container.

property expires_at: datetime
Returns:

The time when this session expires.

property hostname: str
Returns:

The unique hostname for this session

save(*args, **kwargs)[source]

Save the session instance, starting or stopping the service if needed.

Return type:

None

save_without_historical_record(*args, **kwargs)

Save model without saving a historical record

Make sure you know what you’re doing before you use this method.

property service: Service
Returns:

The service for this session, could be active or inactive.

start()[source]

Starts the service for this session, ensuring that the workstation_image is ready to be used and that WORKSTATIONS_MAXIMUM_SESSIONS has not been reached in this region.

Raises:

ComponentException – If the service cannot be started.

Return type:

None

stop()[source]

Stop the service for this session, cleaning up all of the containers.

Return type:

None

property task_kwargs: dict
Returns:

The kwargs that need to be passed to celery to get this object

update_status(*, status)[source]

Updates the status of this session.

Parameters:

status (((0, Queued), (1, Started), (2, Running), (3, Failed), (4, Stopped))) – The new status for this session.

Return type:

None

property workstation_url: str
Returns:

The url that users will use to access the workstation instance.

class grandchallenge.workstations.models.SessionGroupObjectPermission(id, permission, group, content_object)[source]
Parameters:

id (AutoField) – Primary key: ID

Relationship fields:

Parameters:

  • permission (ForeignKey to Permission) – Permission (related name: sessiongroupobjectpermission)

  • group (ForeignKey to Group) – Group (related name: sessiongroupobjectpermission)

  • content_object (ForeignKey to Session) – Content object (related name: sessiongroupobjectpermission)

exception DoesNotExist
exception MultipleObjectsReturned
class grandchallenge.workstations.models.SessionUserObjectPermission(id, permission, user, content_object)[source]
Parameters:

id (AutoField) – Primary key: ID

Relationship fields:

Parameters:

  • permission (ForeignKey to Permission) – Permission (related name: sessionuserobjectpermission)

  • user (ForeignKey to User) – User (related name: sessionuserobjectpermission)

  • content_object (ForeignKey to Session) – Content object (related name: sessionuserobjectpermission)

exception DoesNotExist
exception MultipleObjectsReturned
class grandchallenge.workstations.models.Workstation(*args, **kwargs)[source]

Store the title and description of a workstation.

Parameters:

  • title (CharField) – Title

  • description (TextField) – Description

  • slug (AutoSlugField) – Slug

  • id (UUIDField) – Primary key: Id

  • created (DateTimeField) – Created

  • modified (DateTimeField) – Modified

  • logo (JPEGField) – Logo

  • public (BooleanField) – Public. If True, all logged in users can use this viewer, otherwise, only the users group can use this viewer.

Relationship fields:

Parameters:

  • editors_group (OneToOneField to Group) – Editors group (related name: editors_of_workstation)

  • users_group (OneToOneField to Group) – Users group (related name: users_of_workstation)

  • config (ForeignKey to WorkstationConfig) – Config (related name: workstation)

Reverse relationships:

Parameters:

  • phase (Reverse ForeignKey from Phase) – All phases of this workstation (related name of workstation)

  • algorithm (Reverse ForeignKey from Algorithm) – All algorithms of this workstation (related name of workstation)

  • archive (Reverse ForeignKey from Archive) – All archives of this workstation (related name of workstation)

  • workstationuserobjectpermission (Reverse ForeignKey from WorkstationUserObjectPermission) – All workstation user object permissions of this workstation (related name of content_object)

  • workstationgroupobjectpermission (Reverse ForeignKey from WorkstationGroupObjectPermission) – All workstation group object permissions of this workstation (related name of content_object)

  • workstationimage (Reverse ForeignKey from WorkstationImage) – All workstation images of this workstation (related name of workstation)

  • readerstudy (Reverse ForeignKey from ReaderStudy) – All reader studies of this workstation (related name of workstation)

exception DoesNotExist
exception MultipleObjectsReturned
property active_image
Returns:

The desired image version for this workstation or None

save(*args, **kwargs)[source]

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

class grandchallenge.workstations.models.WorkstationGroupObjectPermission(id, permission, group, content_object)[source]
Parameters:

id (AutoField) – Primary key: ID

Relationship fields:

Parameters:

  • permission (ForeignKey to Permission) – Permission (related name: workstationgroupobjectpermission)

  • group (ForeignKey to Group) – Group (related name: workstationgroupobjectpermission)

  • content_object (ForeignKey to Workstation) – Content object (related name: workstationgroupobjectpermission)

exception DoesNotExist
exception MultipleObjectsReturned
class grandchallenge.workstations.models.WorkstationImage(*args, **kwargs)[source]

A WorkstationImage is a docker container image of a workstation.

Parameters:

  • workstation – A Workstation can have multiple WorkstationImage, that represent different versions of a workstation

  • http_port – This container will expose a http server on this port

  • websocket_port – This container will expose a websocket on this port. Any relative url that starts with /mlab4d4c4142 will be proxied to this port.

  • initial_path – The initial path that users will navigate to in order to load the workstation

  • id (UUIDField) – Primary key: Id

  • created (DateTimeField) – Created

  • modified (DateTimeField) – Modified

  • image (FileField) – Image. .tar.gz archive of the container image produced from the command ‘docker save IMAGE | gzip -c > IMAGE.tar.gz’. See https://docs.docker.com/engine/reference/commandline/save/

  • image_sha256 (CharField) – Image sha256

  • latest_shimmed_version (CharField) – Latest shimmed version

  • import_status (PositiveSmallIntegerField) – Import status

  • is_manifest_valid (BooleanField) – Is manifest valid. Is this image’s manifest valid?

  • is_in_registry (BooleanField) – Is in registry. Is this image in the container registry?

  • status (TextField) – Status

  • size_in_storage (PositiveBigIntegerField) – Size in storage. The number of bytes stored in the storage backend

  • size_in_registry (PositiveBigIntegerField) – Size in registry. The number of bytes stored in the registry

  • comment (TextField) – Comment. Add any information (e.g. version ID) about this image here.

  • is_desired_version (BooleanField) – Is desired version

Relationship fields:

Parameters:

  • creator (ForeignKey to User) – Creator (related name: workstationimage)

  • user_upload (ForeignKey to UserUpload) – User upload (related name: workstationimage)

Reverse relationships:

Parameters:
exception DoesNotExist
exception MultipleObjectsReturned
save(*args, **kwargs)[source]

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

class grandchallenge.workstations.models.WorkstationImageGroupObjectPermission(id, permission, group, content_object)[source]
Parameters:

id (AutoField) – Primary key: ID

Relationship fields:

Parameters:

  • permission (ForeignKey to Permission) – Permission (related name: workstationimagegroupobjectpermission)

  • group (ForeignKey to Group) – Group (related name: workstationimagegroupobjectpermission)

  • content_object (ForeignKey to WorkstationImage) – Content object (related name: workstationimagegroupobjectpermission)

exception DoesNotExist
exception MultipleObjectsReturned
class grandchallenge.workstations.models.WorkstationImageUserObjectPermission(id, permission, user, content_object)[source]
Parameters:

id (AutoField) – Primary key: ID

Relationship fields:

Parameters:

  • permission (ForeignKey to Permission) – Permission (related name: workstationimageuserobjectpermission)

  • user (ForeignKey to User) – User (related name: workstationimageuserobjectpermission)

  • content_object (ForeignKey to WorkstationImage) – Content object (related name: workstationimageuserobjectpermission)

exception DoesNotExist
exception MultipleObjectsReturned
class grandchallenge.workstations.models.WorkstationUserObjectPermission(id, permission, user, content_object)[source]
Parameters:

id (AutoField) – Primary key: ID

Relationship fields:

Parameters:

  • permission (ForeignKey to Permission) – Permission (related name: workstationuserobjectpermission)

  • user (ForeignKey to User) – User (related name: workstationuserobjectpermission)

  • content_object (ForeignKey to Workstation) – Content object (related name: workstationuserobjectpermission)

exception DoesNotExist
exception MultipleObjectsReturned
grandchallenge.workstations.models.delete_workstation_groups_hook(*_, instance, using, **__)[source]

Deletes the related groups.

We use a signal rather than overriding delete() to catch usages of bulk_delete.