🆕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.

Bring Your Own Bench Image Steps

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.

For easy reference, you can find examples of preconfigured Bench images on the Illumina website which you can copy to your local machine and edit to suit your needs.

Bench-console provides an example to build a minimal image compatible with ICA Bench to run a SSH Daemon.

Bench-web provides an example to build a minimal image compatible with ICA Bench to run a Web Daemon.

Bench-rstudio provides an example to build a minimal image compatible with ICA Bench to run a rStudio Open Source.

These examples come with information on the available parameters.

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.

If you want to build on a mac with Apple Silicon, then the build command is docker buildx build --platform linux/amd64 -f Dockerfile -t mybenchimage:0.0.1 .

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 (HTTP), console access (SSH) 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 + Create 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 (HTTP) 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 (SSH) 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.

The password needed for SSH access is any one of your personal API keys

Command-line Interface

To execute the commands, your workspace needs a way to run them such as the inclusion of an SSH daemon, be it integrated into your web access image or into your console access. There is no need to download the workspace command-line interface, you can run it from within the workspace.

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.

Do not run containers as root as this is bad security practice.

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.

Name	Description	Example Values
ICA_WORKSPACE	The unique identifier related to the started workspace. This value is bound to a workspace and will never change.	32781195
ICA_CONSOLE_ENABLED	Whether Console access is enabled for this running workspace.	true, false
ICA_WEB_ENABLED	Whether Web access is enabled for this running workspace.	true, false
ICA_SERVICE_ACCOUNT_USER_API_KEY	An API key that allows interaction with ICA using the ICA CLI and is bound to the permissions defined at startup of the workspace.
ICA_BENCH_URL	The host part of the public URL which provides access to the running workspace.	use1-bench.platform.illumina.com
ICA_PROJECT_UUID	The unique identifier related to the ICA project in which the workspace was started.
ICA_URL	The ICA Endpoint URL.	https://ica.illumina.com/ica
HTTP_PROXY HTTPS_PROXY	The proxy endpoint in case the workspace was started in restricted mode.
HOME	The home folder.	/data

Configuration Files

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

Name	Description
/etc/workspace-auth	Contains the SSH rsa public/private keypair which is required to be used to run the workspace SSHD.

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

Name	Description
/data	This folder contains all data specific to your workspace. Data in this folder is not persisted in your project and will be removed at deletion of the workspace.
/data/project	This folder contains all your project data.
/data/.software	This folder contains ICA-related software.

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 needs to be available and executable otherwise your workspace will not boot.

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.