Configuration

Server configuration

Configure storage, database access, sessions, and optional email.

Configuration file

For a direct Node.js installation, copy .env.example to .env and start with npm start. Compose uses the project .env and mounted secret files. Native Linux and Proxmox installs use /etc/open-tabletop/open-tabletop.env.

The environment example lists the supported settings. Use values for your own installation.

Setting	Purpose
`DATABASE_URL` / `DATABASE_URL_FILE`	Normal PostgreSQL connection using the runtime role.
`MIGRATE_DATABASE_URL` / `MIGRATE_DATABASE_URL_FILE`	Separate owner connection for schema migrations at startup.
`AUTO_MIGRATE`	Set to `false` only if you will apply the required migrations yourself.
`REDIS_URL` / `REDIS_URL_FILE`	Redis connection for shared authentication and upload rate limits.
`ASSETS_DIR`	Directory for uploaded images and models. Back it up with the database.
`SESSION_TTL_DAYS`	Device session lifetime, from 1 to 365 days; default 30.
`TRUST_PROXY_HOPS`	Exact number of trusted reverse proxies in front of the app, from 0 to 10; default 0.
`PUBLIC_ORIGIN`	Canonical origin used in recovery emails, such as `https://tabletop.example.com`.

Compose uses database host, name, user, and password-file settings instead of requiring a connection URL. Keep the runtime and migration credentials separate.

Forward optional settings through Compose

The bundled Compose file explicitly forwards the database, bootstrap, and SMTP settings. It does not forward every key in .env. To configure proxy trust, session lifetime, or automatic migrations, merge this into docker-compose.override.yml:

services:
  app:
    environment:
      TRUST_PROXY_HOPS: "${TRUST_PROXY_HOPS:-0}"
      SESSION_TTL_DAYS: "${SESSION_TTL_DAYS:-30}"
      AUTO_MIGRATE: "${AUTO_MIGRATE:-true}"

Set the desired values in .env, then recreate the app container. If you already have an override for SMTP, merge these keys into its existing services.app.environment block. Do not create duplicate YAML keys. Changing ASSETS_DIR also requires a matching storage mount; changing a host port requires updating the Compose port mapping.

Redis

Production startup requires Redis unless you explicitly choose the memory store. With Redis selected, protected requests return 503 if it becomes unavailable. RATE_LIMIT_STORE=memory is an explicit fallback for local development; it does not share rate limits across processes.

Apply changes

Restart a direct Node.js service after changing its environment. With Compose, recreate the app container so it receives updated settings:

docker compose up -d --force-recreate app

If application code changed as well, rebuild or pull the intended image using the upgrade procedure.

Email and recovery

Email is optional. Password changes and recovery codes work without it. See Email recovery for SMTP settings and Accounts and permissions for enrollment.

Sources checked: .env.example, docker-compose.yml, server/redis-config.js, server/session-config.js. Reviewed September 29, 2026 against the working source. Published releases may differ; check the changelog for your version.