Bring Your Own Bench Image

Bench images are Docker containers tailored to run in ICA with the necessary permissions, configuration and resources. For more information of Docker images, please refer to https://docs.docker.com/reference/dockerfile/

The following steps are needed to get your bench image running in ICA.

Requirements

You need to have Docker installed in order to build your images.

For your Docker bench image to work in ICA, they must run on Linux X86 architecture, have the correct user id and initialization script in the Docker file.

Scripts

The following scripts must be part of your Docker bench image. Please refer to the examples from the Illumina website for more details.

Init Script (Dockerfile)

This script copies the ica_start.sh file which takes care of the Initialization and termination of your workspace to the location in your project from where it can be started by ICA when you request to start your workspace.

# Init script invoked at start of a bench workspace
COPY --chmod=0755 --chown=root:root ${FILES_BASE}/ica_start.sh /usr/local/bin/ica_start.sh

User (Dockerfile)

The user settings must be set up so that bench runs with UID 1000.

# Bench workspaces need to run as user with uid 1000 and be part of group with gid 100
RUN adduser -H -D -s /bin/bash -h ${HOME} -u 1000 -G users ica

Shutdown Script (ica_start.sh)

To do a clean shutdown, you can capture the sigterm which is transmitted 30 seconds before the workspace is terminated.

# Terminate function
function terminate() {
        # Send SIGTERM to child processes
        kill -SIGTERM $(jobs -p)

        # Send SIGTERM to waitpid
        echo "Stopping ..."
        kill -SIGTERM ${WAITPID}
}

# Catch SIGTERM signal and execute terminate function.
# A workspace will be informed 30s before forcefully being shutdown.
trap terminate SIGTERM

# Hold init process until TERM signal is received
tail -f /dev/null &
WAITPID=$!
wait $WAITPID

Building a Bench Image

Once you have Docker installed and completed the configuration of your Docker files, you can build your bench image.

1. Open the command prompt on your machine.

2. Navigate to the root folder of your Docker files.

3. Execute docker build -f Dockerfile -t mybenchimage:0.0.1 . with mybenchimage being the name you want to give to your image and 0.0.1 replaced with the version number which you want your bench image to be. For more information on this command, see https://docs.docker.com/reference/cli/docker/buildx/build/

4. Once the image has been built, save it as docker tar file with the command docker save mybenchimage:0.0.1 | bzip2 > ../mybenchimage-0.0.1.tar.bz2 The resulting tar file will appear next to the root folder of your docker files.

Upload Your Docker Image to ICA

1. Open ICA and log in.

2. Go to Projects > your_project > Data.

3. For small Docker images, upload the docker image file which you generated in the previous step. For large Docker images use the service connector to better performance and reliability to import the Docker image.

4. Select the uploaded image file and perform Manage > Change Format.

5. From the format list, select DOCKER and save the change.

6. Go to System Settings > Docker Repository > Create > Image.

7. Select the uploaded docker image and fill out the other details.

   • Name: The name by which your docker image will be seen in the list

   • Version: A version number to keep track of which version you have uploaded. In our example this was 0.0.1

   • Description: Provide a description explaining what your docker images does or is suited for.

   • Type: The type of this image is Bench. The Tool type is reserved for tool images.

   • Cluster compatible: [For Future Use, not currently supported] Indicates if this docker images is suited for cluster computing

   • Access: This setting must match the available access options of your Docker image. You can choose web access, console access or both. What is selected here becomes available on the + New Workspace screen. Enabling an option here which your Docker image does not support, will result in access denied errors when trying to run the workspace.

   • Regions: If your tenant has access to multiple regions, you can select to which regions to replicate the docker image.

8. Once the settings are entered, select Save. The creation of the Docker image typically takes between 5 and 30 minutes. The status of your docker image will be partial during creation and available once completed.

Start Your Bench Image

1. Navigate to Projects > your_project > Bench > Workspaces.

2. Create a new workspace with + New Workspace or edit an existing workspace.

3. Fill in the bench workspace details according to Workspaces.

4. Save your changes.

5. Select Start Workspace

6. Wait for the workspace to be started and you can access it either via console or the GUI.

Access Bench Image

Once your bench image has been started, you can access it via console, web or both, depending on your configuration.

• Web access is done from either Projects > your_project > Bench > Workspaces > your_Workspace > Access tab or from the link provided at provided in your running workspace at Projects > your_project > Bench > Workspaces > your_Workspace > Details tab > Access section.

• Console access is performed from your command prompt by going to the path provided in your running workspace at Projects > your_project > Bench > Workspaces > your_Workspace > Details tab > Access section.

Restrictions

Root User

• The bench image will be instantiated as a container which will be forcedly started as user with UID 1000 and GID 100.

• You cannot elevate your permissions in a running workspace.

Read-only Root Filesystem

Only the following folders are writeable:

• /data

• /tmp

All other folders are mounted as read-only.

Network Access

For inbound access, the following ports on the container are publicly exposed, depending on the selection made at startup.

• Web: TCP/8888

• Console: TCP/2222

For outbound access, a workspace can be started in two modes:

• Public: Access to public IP’s is allowed using TCP protocol.

• Restricted: Access to list of URLs are allowed.

Context

Environment Variables

At runtime, the following Bench-specific environment variables are made available to the workspace instantiated from the Bench image.

Configuration Files

Following files and folders will be provided to the workspace and made accessible for reading at runtime.

Software Files

At runtime, ICA-related software will automatically be made available at /data/.software in read-only mode.

New versions of ICA software will be made available after a restart of your workspace.

Important Folders

Bench Lifecycle

Workspace Lifecycle

When a bench workspace is instantiated from your selected bench image, the following script is invoked: /usr/local/bin/ica_start.sh

This script is the main process in your running workspace and cannot run to completion as it will stop the workspace and instantiate a restart (see init script).

This script can be used to invoke other scripts.

When you stop a workspace, a TERM signal is sent to the main process in your bench workspace. You can trap this signal to handle the stop gracefully (see shutdown script) and shut down child processes of the main process. The workspace will be forcedly shut down after 30 seconds if your main process hasn’t stopped within the given period.

Troubleshooting

Build Argument

If you get the error "docker buildx build" requires exactly 1 argument when trying to build your docker image, then a possible cause is missing the last . of the command.

Server Connection Error

When you stop the workspace when users are still actively using it, they will receive a message showing a Server Connection Error.