# Docker Installation & Quickstart

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

## 1. Install Docker

Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) (Windows/Mac) or [Docker Engine](https://docs.docker.com/engine/install/) + [Compose plugin](https://docs.docker.com/compose/install/linux/) (Linux). Confirm it's working:

```bash
docker --version
docker compose version
```

If you were given GPU-accelerated segmentation models (StarDist/Cellpose), you'll also need the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) 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`](https://github.com/apple/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.

```bash
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:
  ```bash
  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:

```bash
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:

```bash
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](webgui-quickstart.md))

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

## 4. Run a pipeline directly (no GUI)

```bash
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:

```bash
docker compose pull
docker compose up -d
```