Getting started

Trove KB runs as one app container and Postgres 16. Nothing else is required: no Redis, no queue, no search service. Webhook retries run from a worker inside the app, and search is a Postgres tsvector column.

Quick start

git clone https://github.com/joshhearne/trove-kb.git
cd trove-kb
cp .env.example .env
# set POSTGRES_PASSWORD, match it in DATABASE_URL, and:
#   openssl rand -base64 32   -> AUTH_SECRET
docker compose up -d

The app publishes on http://localhost:3080. The first visit opens a one-time setup screen that creates the administrator account; there is no default password. Migrations run automatically on container start.

The install page generates a complete .env with fresh secrets for your choices of storage, vault mode, and single sign-on.

What to set

Value	Why it matters
POSTGRES_PASSWORD and DATABASE_URL	The same password appears in both.
AUTH_SECRET	Signs sessions. Losing it signs everyone out after a restore.
APP_URL	The origin people actually browse to. Cookies are Secure as soon as it is https, the OAuth state check is built from it, and Better Auth rejects requests whose origin does not match it. A mismatch shows up as a sign-in page that loops.
APP_PORT and APP_BIND	The host port, and whether it is on the LAN (0.0.0.0) or only reachable from this host (127.0.0.1) for a tunnel or reverse proxy.
SEED_ON_START=true	Loads the starter doc types on first boot. Idempotent; safe to leave on.

Starter content

With SEED_ON_START=true the first boot loads a pack of doc types with the option lists they need: Vendor, ISP, Firewall, Switch, Wi-Fi, Printer, Server, Rack, Domain/DNS, and M365/Google Tenant. SEED_LOCALE=en-GB gives British spelling (“Fibre”). See Starter doc types.

A second stack on the same host

ENV_FILE lets a second copy (a test instance, a staging copy) run from its own file without touching the deployment’s .env:

ENV_FILE=.env.test APP_PORT=3090 docker compose -p trove-kb-test up -d

Compose interpolates ${X} from .env alone, never from ENV_FILE, so APP_URL and APP_PORT for the second stack are passed on the shell.

Behind a tunnel

Set APP_BIND=127.0.0.1, APP_URL=https://docs.yourdomain.com, and publish the hostname with cloudflared, Caddy, or nginx pointing at 127.0.0.1:3080. Nothing is open to the internet. See Cloudflare.

Updating

git pull
docker compose up -d --build

Migrations are additive and run on start. Take a pg_dump first; see Backup and restore.