Skip to main content
Version: 25.3

Custom environments

In addition to the Seqera-provided container images, you can provide your own custom container environments by augmenting the Seqera-provided images with a list of Conda packages or by providing your own base container image. Studios uses the Wave service to build custom container images.

For ready-to-use examples, see Example custom Studios.

Conda packages​

Prerequisites
  • Wave must be configured. For more information, see Wave containers.
  • The workspace Admin needs to set a target repository per workspace, in Settings > Studios > Container repository. If no repository configuration is specified, the build will fail. Each workspace must have credentials available to push to the specified repository.

Conda package syntax​

When adding a new Studio, you can customize its configuration to install a list of Conda packages to the container image. The supported schema is identical to that used by the Conda environment.yml file. For more information on the Conda environment file, see Creating an environment file manually.

Example environment.yml file
channels:
- conda-forge
dependencies:
- numpy
- pip:
- matplotlib
- seaborn
Pin Python to the template's version

The JupyterLab template installs JupyterLab and its extensions with Conda, in /opt/conda, and other templates install their language runtimes there, such as R in R-IDE. Wave 1.34.0 and later, including the Seqera-hosted Wave service, resolve your packages into a separate environment and then copy it into the same /opt/conda. Files at the same paths are replaced with your versions, and the rest of the template's environment stays as it was. If your packages resolve to a different Python minor version than the template's, JupyterLab starts under your Python while its extensions are still installed for the template's Python. The session starts but notebooks don't open, and the notebook tab shows a loading spinner indefinitely.

To avoid this:

  • Pin python to the template's version, for example python=3.13 for JupyterLab 4.2.5. An unpinned python resolves to the latest release. Container image templates lists the JupyterLab template's packages. For other templates, run python --version in a terminal in a Studio started from the unmodified template.
  • Pin other interpreters that the template installs with Conda in the same way, such as r-base in R-IDE.
  • Don't list packages that the template already includes, such as jupyterlab or jupyterlab-git, unless you need a different version. Packages that depend on them can also pull in newer versions that replace the template's.

To fix an affected Studio, add a new Studio with the corrected environment file.

To create a Studio with custom Conda packages, see Add a Studio.

Custom container image​

For advanced use cases, you can build your own container image.

note

Public container registries are supported by default. Amazon Elastic Container Registry (ECR) is the only supported private container registry.

Prerequisites
  • A container image.
  • Access to a container image repository, either a public container registry or a private Amazon ECR repository.

Dockerfile configuration​

For your custom container image, you must use a Seqera-provided base image and include several additional build steps for compatibility with Studios. To create a Studio with a custom image, see Add a Studio. Custom images must include an io.seqera.connect.version label specifying the connect-client version used. Platform uses this label to determine available functionality when configuring and launching the Studio.

note

Studios will start without this label, but certain features (such as SSH connectivity) will be unavailable.

Ports​

The container must use the value of the CONNECT_TOOL_PORT environment variable as the listening port for any interactive software you include in your custom container.

Signals​

Upon termination, the container's main process must handle the SIGTERM signal and perform any necessary cleanup. After a 30-second grace period, the container receives the SIGKILL signal.

Minimal Dockerfile​

The minimal Dockerfile includes directives to accomplish the following:

  • Pull a Seqera-provided base image with prerequisite binaries.
  • Set an image label indicating the version used.
  • Copy the connect binary into the build.
  • Set the container entry point.

Customize the following Dockerfile to include any additional software that you require:

Minimal Dockerfile
# Add a default Connect client version. Can be overridden by build arg
ARG CONNECT_CLIENT_VERSION="0.8"

# Seqera base image
FROM public.cr.seqera.io/platform/connect-client:${CONNECT_CLIENT_VERSION} AS connect

# 1. Add connect version label to image metadata
ARG CONNECT_CLIENT_VERSION
LABEL io.seqera.connect.version="${CONNECT_CLIENT_VERSION}"

# 2. Add connect binary
COPY --from=connect /usr/bin/connect-client /usr/bin/connect-client

# 3. Install connect dependencies
RUN /usr/bin/connect-client --install

# 4. Configure connect as the entrypoint
ENTRYPOINT ["/usr/bin/connect-client", "--entrypoint"]

For example, to run a basic Python-based HTTP server, build a container from the following Dockerfile. When a Studio runs the custom template environment, the value for the CONNECT_TOOL_PORT environment variable is provided dynamically.

Example Dockerfile with Python HTTP server
# Add a default Connect client version. Can be overridden by build arg
ARG CONNECT_CLIENT_VERSION="0.8"

# Seqera base image
FROM public.cr.seqera.io/platform/connect-client:${CONNECT_CLIENT_VERSION} AS connect

FROM ubuntu:20.04
RUN apt-get update --yes && apt-get install --yes --no-install-recommends python3

ARG CONNECT_CLIENT_VERSION
LABEL io.seqera.connect.version="${CONNECT_CLIENT_VERSION}"
COPY --from=connect /usr/bin/connect-client /usr/bin/connect-client
RUN /usr/bin/connect-client --install
ENTRYPOINT ["/usr/bin/connect-client", "--entrypoint"]

CMD ["/usr/bin/bash", "-c", "python3 -m http.server $CONNECT_TOOL_PORT"]

Getting started with custom container images​

You can review a series of example custom Studio environment container images here.

Inspect container augmentation build status​

You can inspect the progress of a custom container image build, including any errors if the build fails. A link to the Wave service container build report is always available for builds. If the build fails, the Studio session has the build-failed status. The details about build failures are available when inspecting the session details in the Error report tab.

To inspect the status of an ongoing build, or a successful or failed build, complete the following steps:

  1. Select the Studios tab in Seqera Platform.
  2. From the list of sessions, select the name of the session with building or build-failedstatus that you want to inspect, and then select View.
  3. In the Details tab, scroll to Build reports and select Summary to open the Wave service container build report for your build.
  4. Optional: If the build failed, select the Error report tab to view the errors associated with the build failure.