Installation Guide

WhoDB can run as a container, a standalone binary, a desktop app, or a local source checkout.

Installation Methods

Docker (Recommended)

Docker Compose

services:
  whodb:
    image: clidey/whodb:latest
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - WHODB_LOG_LEVEL=info
      # Keeps encrypted login sessions valid across container recreation.
      # Generate once with: openssl rand -hex 32
      - WHODB_ENCRYPTION_KEY=replace_with_openssl_rand_hex_32
    restart: unless-stopped
    volumes:
      - whodb-data:/data

volumes:
  whodb-data:

Session Storage

WhoDB keeps login sessions server-side. When you log in from a browser, WhoDB stores your database credentials encrypted (AES-256-GCM) in a local SQLite file under its data directory, and the browser only holds an opaque, HttpOnly session cookie — never the credentials themselves.

Without any configuration, this works out of the box: a plain docker run generates an encryption key on first start and keeps you logged in until the container is recreated (at which point you simply log in again). To keep sessions valid across upgrades and restarts:

• Mount /data as a volume so the encrypted session database and generated key persist.
• Set WHODB_ENCRYPTION_KEY to a stable 64-character hex string (openssl rand -hex 32) so the key does not depend on the container's filesystem.

If WhoDB sits behind an HTTPS-terminating reverse proxy (nginx, Traefik, Caddy, a cloud load balancer), also set WHODB_SECURE=true so the session cookie is marked Secure. Leave it unset for plain HTTP, including local development — WhoDB does not infer HTTPS from proxy headers, and setting it on an HTTP deployment causes the browser to drop the cookie.

Binary Installation

Download the appropriate release artifact from GitHub Releases, make it executable if needed, and run it:

chmod +x whodb
./whodb

Build From Source

Prerequisites

• Go 1.26.1 or newer
• Node.js and pnpm

Build Steps

Development Mode

Use two terminals:

cd core
go run ./cmd/whodb

cd frontend
pnpm start

The frontend dev server runs on http://localhost:3000 and proxies its backend requests to the WhoDB server.

Desktop App

The desktop app lives in desktop-ce/ and uses the same frontend and backend codepaths. See Desktop App for the current behavior.

Common Environment Variables

Server

AI Providers

Generic OpenAI-compatible providers can be added with the WHODB_AI_GENERIC_<ID>_* pattern. See Setting Up AI Providers.

Cloud Providers

See Cloud Providers for examples and discovery details.

Database Connection Profiles

WhoDB can preload connection profiles from environment variables so they appear on the login page.

Profiles work for every database type in the catalog: the prefix is WHODB_ followed by the uppercased type name. Examples for the core types include:

• WHODB_POSTGRES
• WHODB_COCKROACHDB
• WHODB_MYSQL
• WHODB_MARIADB
• WHODB_TIDB
• WHODB_SQLITE3
• WHODB_MONGODB
• WHODB_REDIS
• WHODB_ELASTICSEARCH
• WHODB_CLICKHOUSE
• WHODB_DUCKDB
• WHODB_MEMCACHED

The same pattern applies to the rest of the catalog, such as WHODB_VALKEY, WHODB_DRAGONFLY, WHODB_OPENSEARCH, WHODB_YUGABYTEDB, WHODB_QUESTDB, and WHODB_FERRETDB.

Two formats are supported:

export WHODB_POSTGRES='[
  {"alias":"prod","host":"db.example.com","user":"postgres","password":"secret","database":"app","port":"5432"},
  {"alias":"staging","host":"staging.example.com","user":"postgres","password":"secret","database":"app","port":"5432"}
]'

Each profile object supports these common fields:

SSL Example

For profile-based connections, the backend accepts both certificate content keys and server-side file-path keys:

export WHODB_POSTGRES_1='{
  "alias": "prod",
  "host": "db.example.com",
  "user": "postgres",
  "password": "secret",
  "database": "app",
  "port": "5432",
  "advanced": {
    "SSL Mode": "verify-ca",
    "SSL CA Path": "/etc/certs/ca.pem",
    "SSL Client Cert Path": "/etc/certs/client.pem",
    "SSL Client Key Path": "/etc/certs/client-key.pem"
  }
}'

Custom Port Example

PORT=3000 ./whodb

To publish the default container listener on host port 3000:

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

If you intentionally change the internal listener with PORT, map the same internal port:

docker run -d \
  -e PORT=3000 \
  -p 3000:3000 \
  clidey/whodb:latest

Verify The Install

Troubleshooting

Related Pages