logo

WhoDB

Integrations

Docker Integration

Docker Integration

Docker is the fastest way to run WhoDB.

Run WhoDB

Bash

docker run -d \
  --name whodb \
  -p 8080:8080 \
  clidey/whodb:latest

Open http://localhost:8080.

Docker Compose

Save as docker-compose.yml:

YAML

services:
  whodb:
    image: clidey/whodb:latest
    container_name: whodb
    ports:
      - "8080:8080"
    environment:
      WHODB_LOG_LEVEL: info
    restart: unless-stopped

Run:

Bash

docker compose up -d

Host Port 3000

If you only want the host URL to be http://localhost:3000, keep the container listener on 8080 and change the host-side port:

Bash

docker run -d \
  --name whodb \
  -p 3000:8080 \
  clidey/whodb:latest

Compose:

YAML

services:
  whodb:
    image: clidey/whodb:latest
    ports:
      - "3000:8080"

If you intentionally change WhoDB's internal listener, set PORT and map that internal port:

YAML

services:
  whodb:
    image: clidey/whodb:latest
    environment:
      PORT: "3000"
    ports:
      - "3000:3000"

Persistent Login Sessions

WhoDB encrypts login sessions and stores them in /data inside the container. Without a mounted volume, a plain docker run still works, but sessions reset whenever the container is recreated. To keep sessions across restarts and upgrades, mount /data and set a stable encryption key:

YAML

services:
  whodb:
    image: clidey/whodb:latest
    ports:
      - "8080:8080"
    volumes:
      - whodb-data:/data
    environment:
      # Generate once with: openssl rand -hex 32
      WHODB_ENCRYPTION_KEY: replace_with_openssl_rand_hex_32

volumes:
  whodb-data:

If WhoDB is reachable only over HTTPS (typically via a reverse proxy or load balancer in front of the container), also set WHODB_SECURE: "true" so the session cookie is marked Secure. Leave it unset for plain HTTP.

See Session Storage for the full explanation of how sessions are encrypted and stored.

Connect To Host Databases

From inside a container, localhost means the WhoDB container itself. Use the right hostname for your database:

  • Another Compose service: use the service name, such as postgres.
  • Database running on the Docker host: use host.docker.internal where supported.
  • Remote database: use its network hostname or IP.

Example with PostgreSQL:

YAML

services:
  whodb:
    image: clidey/whodb:latest
    ports:
      - "8080:8080"
    depends_on:
      - postgres

  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: whodb
      POSTGRES_PASSWORD: whodb
      POSTGRES_DB: whodb
    ports:
      - "5432:5432"

Use postgres as the host in the WhoDB login form.

Health Check

WhoDB CE exposes GET /health, returning plain text ok.

YAML

services:
  whodb:
    image: clidey/whodb:latest
    ports:
      - "8080:8080"
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:8080/health | grep -qx ok"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s

Logs

Use standard Docker logs:

Bash

docker logs -f whodb

Or write WhoDB logs to mounted files:

YAML

services:
  whodb:
    image: clidey/whodb:latest
    ports:
      - "8080:8080"
    environment:
      WHODB_LOG_FORMAT: json
      WHODB_LOG_FILE: default
      WHODB_ACCESS_LOG_FILE: default
    volumes:
      - ./logs:/var/log/whodb

AI Providers

Pass provider credentials or endpoints as environment variables:

YAML

services:
  whodb:
    image: clidey/whodb:latest
    ports:
      - "8080:8080"
    environment:
      WHODB_OPENAI_API_KEY: ${WHODB_OPENAI_API_KEY}
      WHODB_ANTHROPIC_API_KEY: ${WHODB_ANTHROPIC_API_KEY}
      WHODB_OLLAMA_HOST: host.docker.internal
      WHODB_OLLAMA_PORT: "11434"

Related Pages

Installation

See non-Docker install options.

Monitoring Integration

Configure health checks and logging.

Next

AWS Deployment