Skip to main content

Custom environments

In addition to the Seqera-provided container images, you can build custom container environments by augmenting the Seqera-provided images with Conda packages or by supplying 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​

Augment a Seqera-provided image with Conda packages to add the tools you need to a Studio session. You can also augment a custom container image.

Prerequisites

You need the following:

  • Wave configured. See Wave containers.
  • A target repository set per workspace by the workspace Admin, in Settings > Studios > Container repository.
  • Workspace credentials with push access to the target repository.

Conda package syntax​

When adding a new Studio, you can install Conda packages in the container image. The supported schema is identical to the Conda environment.yml file. For more information, see Creating an environment file manually.

Example environment.yml
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 resolves your packages into a separate environment and then copies 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.6.0. 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.

Conda packages can only be set when you add a Studio. 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.

Public container registries are supported by default. The following private container registries are supported:

On AWS Cloud, Azure Cloud, and Google Cloud compute environments, the instance authenticates to the private registry of its own cloud provider with the instance identity, so no container registry credentials are needed for the pull:

  • AWS Cloud: Seqera attaches the AmazonEC2ContainerRegistryPullOnly managed policy to the instance role. Images in another AWS account need a repository policy that grants that role pull access.
  • Azure Cloud: Seqera grants the compute environment's managed identity pull access to registries in the compute environment's subscription. For a registry in another subscription, assign the AcrPull role to the managed identity on that registry. Managed identities cannot access registries in another tenant.
  • Google Cloud: Images in Artifact Registry (<location>-docker.pkg.dev) and Container Registry (gcr.io or a regional host such as eu.gcr.io) are supported. Grant the compute environment's service account the Artifact Registry Reader role (roles/artifactregistry.reader) on the repository.

To use SSH connectivity in a Studio with an image from a private registry, add workspace credentials for that registry. Seqera uses these credentials, not the instance identity, to read the image's io.seqera.connect.version label. Without them, you cannot create the Studio with SSH enabled.

Prerequisites

You need the following:

  • A container image.
  • Access to a container image repository, either a public container registry or a private Amazon ECR, Azure ACR, or Google Artifact Registry 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. Seqera Platform uses this label to determine available functionality when configuring and launching the Studio.

note

Studios starts without this label, but certain features (such as SSH connectivity) are 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:

  • 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 you require:

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

# 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 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.14"

# 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"]

Conda augmentation of custom images​

You can augment a custom container image with Conda packages, in the same way as a Seqera-provided image template. Your image doesn't need its own Conda installation. Wave builds the Conda environment in a separate stage and copies it into your image.

warning

Conda augmentation hasn't been validated across custom images. Before you share an augmented custom image, start a test Studio from it and check that both your own tools and the added Conda packages work.

The Conda packages prerequisites also apply. Wave must be configured, the workspace Admin must set a target container repository for the workspace, and the workspace credentials must have push access to it.

How the augmented image is built​

Studios builds the augmented image with Wave, using the conda/micromamba:v2 multi-stage build template:

  1. Wave resolves the packages in your environment file into a Conda environment in a build stage based on mambaorg/micromamba.
  2. Wave then uses your custom image as the base of the final stage, copies the resolved environment into it at MAMBA_ROOT_PREFIX (/opt/conda), and prepends /opt/conda/bin to PATH.

Wave doesn't add micromamba to the final image, only the resolved environment.

The build pushes a new image to the workspace container repository, named according to the workspace container naming strategy. Your source image in its own registry is not modified.

Image compatibility​

Check how your image is laid out before you augment it:

caution
  • The resolved environment is copied to /opt/conda. If your image already has content at that path, the copied environment is written over it.
  • If your image installs its analysis tooling outside /opt/conda, through apt or a system Python for example, the augmented packages are installed against the Conda environment's own interpreter.
  • Binaries in /opt/conda/bin take precedence on PATH, which can shadow the equivalents in your image.
note

Studios builds the environment with micromamba, currently the only supported package manager for augmenting custom images.

When you add the Studio, Seqera Platform rejects the request with a 400 error, before any Wave build starts, if:

  • The Conda environment isn't valid.
  • The destination container repository is invalid or not allowed.

If an augmented build fails, the Studio session has the build-failed status. See Inspect container augmentation build status for the build report and error details.

Custom container image examples​

For example custom Studio environment container images, see the custom Studios examples repository.

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 available for every build. If the build fails, the Studio session has the build-failed status, and the build error details are available in the session's Error report tab.

To inspect the status of a build, complete the following:

  1. Select the Studios tab in Seqera Platform.
  2. From the list of sessions, select the name of the session with building or build-failed status, 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 build errors.
On this Page