# With Docker

> Run decisio in a container on a GPU host, from the release image pinned by digest, with the weights in a volume and a restart policy.

Source: https://opendecisio.com/docs/deploy/docker/

One command starts it from the release image; it is ready when `/health` answers.

 

```
docker run -d --gpus all --shm-size 8g --restart unless-stopped \
  -p 127.0.0.1:8000:8000 -v decisio-data:/data \
  ghcr.io/aminry/decisio@sha256:5f758e5cfbf42892f42f62e037f26376154c3e77c5caf6afdd6ccc1a5cd9c4ee
# answers once the first start has fetched the weights
curl -s http://127.0.0.1:8000/health
```

 

Shown, not run: it needs a GPU host with the NVIDIA Container Toolkit, which this check does not have. Its comments are shown above their commands.

 

[Figure: The image holds the server; the weights live in a volume. Your backend reaches the container on port 8000, published on 127.0.0.1 only. Inside, the decisio server runs from the release image, pinned by digest, as a non-root user, and sees one NVIDIA card through the NVIDIA Container Toolkit. The weights live in the decisio-data volume at /data, never in the image, so a restart fetches nothing again.]

 

## 1 What you need

 

- A Linux host with one NVIDIA card, sized as on [a cloud GPU](https://opendecisio.com/docs/deploy/cloud-gpu/#1-pick-your-card).
- Docker with the NVIDIA Container Toolkit, so the container can see the card.

 

## 2 Run it with Compose

 

decisio’s compose file, from the release image:

 

```
name: decisio

services:
  decisio:
    image: ghcr.io/aminry/decisio@sha256:5f758e5cfbf42892f42f62e037f26376154c3e77c5caf6afdd6ccc1a5cd9c4ee
    environment:
      DECISIO_BASE: gemma-4-31b       # the default (measured on 96 GB, runs on 80 GB); qwen3.6-35b-a3b or gemma-4-12b for the others
    ports:
      - "127.0.0.1:8000:8000"
    volumes:
      - decisio-data:/data
    shm_size: "8gb"
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    restart: unless-stopped           # also after a dead engine: the server exits with code 70

volumes:
  decisio-data:
```

 

Shown, not run: decisio's compose.yaml, with the release image in place of its local build; not run at this release (an image built from decisio's main came up with the file on a card on 2026-10-01); [run record](https://github.com/aminry/decisio/tree/v0.18.1/runs/2026-10-01_docker-first-gpu-start).

 

Save it as `compose.yaml` and run `docker compose up -d`. It is ready when `/health` answers 200, as [a healthy server’s answer](https://opendecisio.com/docs/deploy/cloud-gpu/#2-start-the-server) shows.

 

## 3 Choose what it serves

  

| Setting | What it does |
| --- | --- |
| `DECISIO_BASE` | the model: `gemma-4-31b` by default, or `gemma-4-12b`, `qwen3.6-35b-a3b`, or a decisio model repository |
| `DECISIO_MODEL` | a checkpoint instead; it brings the model its `config.json` declares |
| `DECISIO_HOST`, `DECISIO_PORT` | where the server listens inside the container |

 

Arguments after the image name go to the server, so every [server flag](https://opendecisio.com/docs/flags/) works.

 

## 4 What to know

 

- The first start downloads the weights into the `decisio-data` volume at `/data`. They are never part of the image, and a restart does not download them again.
- The container runs as a non-root user, and the port is published on `127.0.0.1` only.
- It checks for an NVIDIA GPU first, and exits with an explanation when it cannot see one.
- When its engine dies, the server exits with code 70. Docker restarts a container when its process exits, not when its health check fails, so `restart: unless-stopped` brings it back.
- After upgrading the image, certify your [tasks](https://opendecisio.com/docs/glossary/#task) again ([Upgrade](https://opendecisio.com/docs/upgrading/)).

 

## 5 Build the image yourself

 

To build from source instead, from a clone of the release:

 

```
git clone --branch v0.18.1 https://github.com/aminry/decisio
cd decisio
uv build --wheel
docker compose up --build
```

 

Shown, not run: it needs a GPU host with the NVIDIA Container Toolkit, which this check does not have.

 

This builds the image from decisio’s own `Dockerfile` and `compose.yaml`, with no image digest to set.

 

## What next

 

- [On a cloud GPU](https://opendecisio.com/docs/deploy/cloud-gpu/): the same server without a container, under systemd or Kubernetes.
- [Requirements and limits](https://opendecisio.com/docs/limits/): every machine, the context length and what was measured on what.
- [Operate](https://opendecisio.com/docs/operating/): health, monitoring and what to watch in production.