Docker Deployment¶

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

Quick Start¶

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¶

# 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

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:

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. On Ubuntu/Debian, the core setup is:

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:

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:

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

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