Install and configure CE

Install WhoDB where it can reach the databases you want to inspect. The browser interface connects through the WhoDB server, so database endpoints and file paths must be accessible from that server.

Choose Docker for a self-hosted browser workspace, a release binary for a local server, or the desktop app for native file dialogs. The CLI is installed separately; see CLI & MCP.

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 on the server. The session store holds database credentials encrypted in a local SQLite file under the data directory. The browser uses an opaque, HttpOnly cookie to identify that session.

On first start, WhoDB generates an encryption key if none is configured. With a plain docker run, replacing the container also replaces its local session storage, so users need to connect again. To retain sessions across replacement:

• 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 this setting from proxy headers. Enabling it for an HTTP deployment prevents the browser from using the cookie correctly.

Binary installation#

Download the artifact for your operating system and architecture from WhoDB releases. Extract it if needed, make it executable, and run it:

chmod +x whodb
./whodb

Build from source#

Prerequisites

• Go matching core/go.mod (currently 1.27.4)
• Node.js matching .nvmrc (currently 26.12.1) and the frontend's pinned pnpm version

Build steps

Development mode

Use two terminals:

1cd core
2go run ./cmd/whodb

1cd frontend
2pnpm start

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

Desktop app#

Choose the desktop app when you want to work locally with native file dialogs and application menus. Follow Desktop app for installation and file access 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.

CLI cloud providers

These variables do not enable provider operations in the CE web server. See Cloud providers for the local CLI workflow.

Database connection profiles#

Use configured profiles when instance users should connect without entering the same endpoint and credentials each time. WhoDB loads these profiles from environment variables and displays their aliases on the connection 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":"development","host":"db.example.com","user":"postgres","password":"replace-me","database":"app","port":"5432"},
  {"alias":"staging","host":"staging.example.com","user":"postgres","password":"replace-me","database":"app","port":"5432"}
]'

Each profile object supports these common fields:

Setting WHODB_DISABLE_CREDENTIAL_FORM=true hides manual credential entry, but it does not add authentication in front of configured profiles. Users who can reach the instance can still select and use them.

TLS example

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

export WHODB_POSTGRES_1='{
  "alias": "development",
  "host": "db.example.com",
  "user": "postgres",
  "password": "replace-me",
  "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#

Continue after installation#