Developer documentation¶

RemoteAppManager¶

The main tornado web application that manages the containers (docker applications) for each user.

Docker image specifications¶

Docker images compliant to the simphony-remote application define a protocol through docker LABEL and environment variables.

Labels¶

Labels are defined with the prefix namespace:

eu.simphony-project.docker

The following labels are currently defined. Their definition can be found in remoteappmanager.docker.docker_labels

ui_name: the UI visible name of the image

icon_128: a base64 encoded png image that will result as an icon

description: a user-readable description of the image

type: a string identifying the type of the container, depending on the original base image (vncapp or webapp)

env: subnamespace for accepted environment variables. See below.

The env is a subnamespace defining the environment variables the image internals can understand. This does not mean that they are the only ones that will be passed to the image.

The naming strategy works around the docker label restrictions of having kebab case vs envvars that are traditionally MACRO_CASE. Additionally, it allows new variables to be added by layers without having to know the variables understood by the base layer.

The strategy is as follows: the name after the env will be converted to uppercase and dashes converted to underscores. For example:

env.x11-width -> container accepts and understands envvar X11_WIDTH

the value of the label is currently unused, and should be left empty.

If your application uses variables with a different convention, or uses double underscores, you will have to define an auxilliary variable and transfer the value in the image startup scripts.

Currently reserved env keys:

x11-width: for the VNC images, the X11 width

x11-height: for the VNC images, the X11 height

x11-depth: for the VNC images, the X11 depth (currently unused, fixed at 16)

startupdata: this variable can be set to a file that will be loaded by an application upon startup

Container Labels¶

When a container is started, the following labels will be added:

url_id: unique identifier that ends up in the URL when the user is redirected

mapping_id: a unique key identifying the combination of image and policy used to start the container.

user: the user that started the container

Environment variables¶

The following environment variables are passed at container startup:

JPY_USER: the username used to login to the Jupyterhub frontend. Can be an email address, or anything else your authenticator accepts.

JPY_BASE_USER_URL: The base URL _path_ where the user has its service.

USER: A unix-likable username to create the container user.

URL_ID: a unique key assigned to the container that will end up in the user-exposed URL to reach the container.

If the image accepts additional envvars (through the env labels mechanism outlined above) these variables will be passed through the configurables mechanism: special variables are recognized and exposed to the user as a configurable UI, then passed to the container at startup. See the reserved env labels for details.

Docker CI for SimPhoNy-Remote¶

This module contains Docker files that can be used to test installations for various platforms.

Please ensure that you are building from a clean repository, since all contents will be copied into the Docker image and may affect the build. For example, if a venv is already present then this will prevent the Python virtual environment inside the container from being set up correctly.

However, running S-R as a Docker container image is NOT fully supported for deployment, since image applications will not be able to be run.

Building SimPhoNy-Remote as a Docker Image¶

It is also possible to build SimPhoNy-Remote as a Docker container image using a Dockerfile script provided for either ubuntu or centos Linux OS:

docker build . --file Dockerfile-<linux os> -t simphony-remote

Alternatively, you can provide the following docker-compose command:

docker-compose build simphony-remote-<linux os>

Running SimPhoNy-Remote as a Docker Image¶

When running, S-R needs to be given a reference to the Docker daemon that contains the applications (also Docker container images) required by the Hub session. Running Docker inside Docker is not recommended, but there are a couple of approaches that can be used as a work around, such as sharing volumes or performing a bind mount.

We have successfully ran a S-R session using a Docker container image by sharing volumes with the following command:

docker run -it -v /var/run/docker.sock:/var/run/docker.sock -p 8000:8000 simphony-remote-<linux os> bash

This will allow a jupyterhub session with user login / management services to be initiated as normal. However, as stated previously, any S-R applications will not be able to run.