Docker Deployment

Deploy Noirdoc with Docker Compose.

Prerequisites

Before you begin, make sure you have:

  • Docker Engine 24 or later
  • Docker Compose V2 (included with Docker Desktop, or install the docker-compose-plugin package)
  • An API key from at least one supported LLM provider (OpenAI, Anthropic, Azure OpenAI, or OpenRouter)

Generate an encryption key

Noirdoc encrypts all provider API keys and sensitive configuration at rest using a Fernet symmetric key. Generate one before starting:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Save the output — you will need it in your docker-compose.yml. If you lose this key, encrypted provider keys cannot be recovered.

Standalone deployment

The fastest way to get started is standalone mode. Create a docker-compose.yml with the following content:

services:
  proxy:
    build: .
    ports:
      - "8000:8000"
    environment:
      - MODE=standalone
      - DATABASE_URL=postgresql+asyncpg://noirdoc:secret@postgres:5432/noirdoc
      - REDIS_URL=redis://redis:6379/0
      - ENCRYPTION_KEY=your-fernet-key
      - STANDALONE_BEARER_TOKEN=your-secret-token
      - STANDALONE_PROVIDER=openai
      - STANDALONE_PROVIDER_KEY=sk-your-openai-key
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: noirdoc
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: noirdoc
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    volumes:
      - redisdata:/data

volumes:
  pgdata:
  redisdata:

Replace your-fernet-key, your-secret-token, and sk-your-openai-key with your actual values.

Start the stack

docker compose up -d

Verify the deployment

curl http://localhost:8000/health

You should see:

{
  "status": "ok",
  "version": "1.0.0",
  "mode": "standalone"
}

Send your first request

curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {"role": "user", "content": "Summarize the case for Max Mustermann, born 15.03.1985."}
    ]
  }'

Noirdoc pseudonymizes the name and date before forwarding to OpenAI, then restores the original values in the response.

For multi-tenant cloud mode configuration, see the Configuration Reference.

Adding Caddy for HTTPS

For production deployments exposed to the internet, add Caddy as a reverse proxy with automatic TLS:

  caddy:
    image: caddy:2-alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
    depends_on:
      - proxy

Create a Caddyfile in the same directory:

api.yourdomain.com {
    reverse_proxy proxy:8000
}

Caddy will automatically obtain and renew a Let’s Encrypt certificate for your domain.

Updating

To update to a new Noirdoc version, pull the latest changes and rebuild:

docker compose down
docker compose build --no-cache
docker compose up -d

Database migrations run automatically on startup. Always back up your PostgreSQL volume before upgrading.

Next steps