Docker Installation & Quickstart

pyCyto is distributed as a container image — no Python environment setup is required.

1. Install Docker

Install Docker Desktop (Windows/Mac) or Docker Engine + Compose plugin (Linux). Confirm it’s working:

docker --version
docker compose version

If you were given GPU-accelerated segmentation models (StarDist/Cellpose), you’ll also need the NVIDIA Container Toolkit on Linux with an NVIDIA GPU.

Experimental: Apple’s native container tool (Mac, no Docker Desktop)

Apple Silicon Macs on macOS 15+ can run OCI images with Apple’s own container CLI instead of Docker Desktop — it uses Apple’s lightweight virtualization framework directly, with no separate VM to manage. This path is experimental and untested against pyCyto — the rest of this guide assumes standard Docker; use this only if you specifically want to avoid Docker Desktop, and expect rough edges.

brew install --cask container
container system start
container --version

Known limitations versus Docker Desktop:

  • No docker compose equivalent yet — each service in docker-compose.yml must be started individually with container run, translating the ports:/volumes: entries into -p/-v flags yourself.

  • No NVIDIA GPU passthrough (not applicable on Apple Silicon anyway) — only CPU-based segmentation (Cellpose/StarDist without CUDA) will work.

  • Registry login uses the same pattern as Docker:

    container login ghcr.io -u <your-username>
container run --rm -p 3003:8000 -v ./data:/data ghcr.io/bpi-oxford/cytotoxicity-pipeline-webgui:latest

If you hit issues on this path, fall back to Docker Desktop (Apple Silicon Macs run it via a lightweight VM and it’s fully supported).

2. Authenticate to the image registry

The pyCyto image is distributed as a private package on GitHub Container Registry. You will have been given a read-only access token — log in once:

echo "<your-token>" | docker login ghcr.io -u <your-username> --password-stdin

3. Run the standalone stack

Your release package includes a docker-compose.yml and a config template (pipeline.yaml / pipeline-resources.yaml). From that directory:

docker compose pull
docker compose up

This starts:

  • cyto — the analysis pipeline engine (idle until invoked; see step 4)

  • webgui — the visual DAG editor, backed by the same pyCyto install (see webgui-quickstart)

Once running, open the web GUI at http://localhost:3003.

4. Run a pipeline directly (no GUI)

docker compose run --rm cyto cyto --pipeline /config/pipeline.yaml -v

Mount your data and config directories into the cyto service’s volumes in docker-compose.yml — see the config template included in your release package for a starting pipeline.yaml.

Updating

New image versions are published to the same registry package as they become available:

docker compose pull
docker compose up -d