Skip to content

Container Images

A Container Image bundles the operating-system libraries, astronomy software, and application entrypoint used by a Session. The image is the software environment; the Session request supplies the Session Kind, resources, command, and mounted storage.

Choose an image

List images that support a Session Kind before creating a Session:

canfar image ls --kind notebook
canfar image ls --kind headless
canfar create notebook IMAGE_NAME --name analysis

The image list and Science Portal are authoritative for available names, versions, and supported kinds. Examples in these docs are illustrative and may not exist in every deployment. A private image also requires access to its Container Registry project.

Build time and run time

Build-time changes are part of the image and can be reproduced by anyone with the Dockerfile and build inputs. Run-time changes inside a Session are not an image release. Keep stable dependencies in the image and save scripts or configuration under persistent /arc storage.

FROM python:3.13-slim

RUN python -m pip install --no-cache-dir astropy numpy
COPY reduce.py /opt/workflow/reduce.py
ENTRYPOINT ["python", "/opt/workflow/reduce.py"]

The base image, packages, and entrypoint must match the Session Kind. A headless image must provide the command that the batch request invokes; a Notebook or application image must provide the application expected by its Session launcher.

Runtime storage

When the deployment provides them, Sessions mount persistent /arc paths and ephemeral /scratch storage. The image does not own those data lifetimes:

/arc/home/<user>                 persistent personal files
/arc/projects/<project>         persistent shared project data
/scratch                         Session-local staging and intermediates

Use /scratch for fast temporary work and copy results to /arc or a persistent VOSpace Service before stopping the Session. See Storage.

What a Server requires of an image

A trusted registry. A Science Platform Server launches images only from the registry hosts its operator trusts; the default is images.canfar.net. A request for an image elsewhere is rejected before anything starts.

A label, to be listed. The Server builds its image list from the labels the Container Registry holds for each image: one label per Session Kind the image supports, named notebook, desktop, desktop-app, carta, firefly, contributed, or headless. The label is set on the image in the registry, and a LABEL line in a Dockerfile has no effect on it. The list is refreshed periodically, every 30 minutes by default, so a newly labelled image takes a while to appear in canfar image ls and the Science Portal. An unlabelled or private image can still be launched by its full name with registry credentials.

No root. Every container runs with your user ID, your group memberships as supplemental groups, no Linux capabilities, and no privilege escalation, so sudo and package installation at run time are unavailable. Install software when you build the image, and write runtime files under your home directory, /scratch, or /tmp.

A shell. The Server runs /bin/sh and cp from your image while preparing the Session's user and group files, so a minimal image still needs both.

Session Kind What the Server does What the image must provide
notebook Starts JupyterLab itself, on port 8888 bash and jupyter lab on the PATH
carta Runs the image's entrypoint CARTA on port 6901, served under the path in SKAHA_SESSION_URL_PATH
desktop-app Opens the application inside a Desktop Session An X11 application and xterm; an optional /skaha/startup.sh wraps the launch
contributed Runs the image's entrypoint A web application on port 5000; see Contributed applications
headless Runs the command you give, or the image's default The command and its dependencies

The Server sets HOME to your persistent home directory. In every Kind except desktop it also sets OMP_NUM_THREADS, MKL_NUM_THREADS, OPENBLAS_NUM_THREADS, and JULIA_NUM_THREADS to the number of cores you requested; see Session limits.

Resource and security considerations

  • Keep credentials out of Dockerfiles, image layers, and command arguments.
  • Pin important dependencies and rebuild when security fixes are needed.
  • Keep images small so pulls and startup do not dominate short workloads.
  • Request only the CPU, memory, and GPU that measurements support.
  • Test the exact image with a small input before launching replicas.

Build and publish

Use the build toolchain documented by your registry or deployment. A generic local workflow is:

docker build -t images.canfar.net/<project>/<image>:<tag> .
docker push images.canfar.net/<project>/<image>:<tag>

The registry project must grant the account permission to push. Use a stable version tag for reproducible workflows and reserve moving tags such as latest for development. See Building Containers and Registry.