# Docker Deployment

Deploys the full VIPR stack: Frontend · API · Celery Worker · Redis.

## Quick Start

```bash
git clone https://codebase.helmholtz.cloud/vipr/vipr-framework.git
cd vipr-framework
cp docker-compose.override.yml.example docker-compose.override.yml
mkdir -p storage
docker compose up --wait
```

- Frontend: http://localhost:5000
- API docs: http://localhost:8000/docs (uncomment `ports` for `vipr-api` in `docker-compose.override.yml`)

## Services

| Service | Purpose | Port |
|---|---|---|
| `redis` | Message broker & result backend | 6379 |
| `vipr-api` | FastAPI backend | 8000 |
| `vipr-worker` | Celery background worker | — |
| `vipr-frontend` | Nuxt.js web interface | 5000 |

## Common Tasks

```bash
# Logs
docker compose logs -f vipr-api

# Restart a service
docker compose restart vipr-worker

# Pull latest images and restart
docker compose pull && docker compose up -d

# Shell access
docker compose exec vipr-api bash
```

## Troubleshooting

**Service won't start**
```bash
docker compose ps
docker compose logs vipr-api
```

**GPU/CUDA inference fails in `vipr-worker`**
GPU inference requires a working NVIDIA driver on the host and the NVIDIA Container Toolkit configured for Docker. First check the host and Docker runtime:
```bash
nvidia-smi
docker info --format '{{json .Runtimes}}'
```

If the host GPU works but Docker does not list an `nvidia` runtime, follow the current [NVIDIA Container Toolkit installation guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html). On Ubuntu/Debian, the core setup is:
```bash
sudo apt-get update && sudo apt-get install -y --no-install-recommends ca-certificates curl gnupg2

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
```

Then uncomment the GPU block for `vipr-worker` in `docker-compose.override.yml`, recreate the worker, and verify GPU access inside the container:
```bash
docker compose up -d --force-recreate vipr-worker
docker compose exec vipr-worker nvidia-smi
```

**Permission denied on storage/**
If the local bind-mounted `storage/` directory was created with mismatched ownership, make it writable for the backend container user:
```bash
sudo chown -R $(id -u):$(id -g) storage/
```

**Storage directory layout** (bind-mounted from `./storage/`)
The application creates the required subdirectories as needed:
```
storage/
├── huggingface/
├── reflectometry/
│   ├── reflectorch/
│   │   ├── configs/
│   │   └── saved_models/
│   ├── flow_models/
│   │   ├── configs/
│   │   └── saved_models/
│   └── panpe/
│       ├── configs/
│       └── saved_models/
├── results/
├── config/
├── plugins/
├── .matplotlib/
└── .torch_cache/
```

**Reset everything**
```bash
docker compose down --volumes
docker compose up -d
```

## Image Sources

Images are pulled from `registry.hzdr.de`:
- `registry.hzdr.de/vipr/vipr-api:latest`
- `registry.hzdr.de/vipr/vipr-frontend:latest`
