Docker deployment
Run commands from timeline-app (or the root of its GitHub repository). Install Docker Engine with the Compose plugin. The suite builds PostgreSQL 16 with native GMP-backed pgmp, a Next.js App Router server on Node 24, and the native SQLite .och converter. Rust and Node build tools remain in separate build stages; the web container runs as the unprivileged node user, which cannot change the application's files (they belong to root; only Next.js's cache folder is writable).
cp .env.example .env
# Edit .env: choose strong, different POSTGRES_PASSWORD and APP_DATABASE_PASSWORD.
docker compose up --build --wait
docker compose ps
Open http://localhost:5173. The first build downloads base images and locked dependencies and compiles both extensions. PostgreSQL becomes healthy first, the one-shot database-setup service creates pgmp and the application's database role, the one-shot migrate service installs the schema, and then the web server starts. /healthz checks database connectivity and the timeline schema. The setup and migration containers exiting successfully is expected. The web and database services restart automatically; Compose must complete migrations before starting a new web container.
There are two database passwords. POSTGRES_PASSWORD is the superuser's, which PostgreSQL's image creates; only database-setup uses it, to create pgmp (which needs a superuser) and the openchronology_app role. APP_DATABASE_PASSWORD is that role's: it is not a superuser and owns the database and everything in it, and the migrations, the app and the mail worker connect as it, as every other package's server does. A bug in the app that reached the database could then not run programs or read files on the database's machine, as a superuser can. Choose two different passwords. Compose passes them using PGPASSWORD, so punctuation does not require URI encoding. Quote values containing # or $ appropriately in .env (single quotes prevent interpolation). Keep .env private; it is excluded from the Docker build context. database-setup sets the role's password from APP_DATABASE_PASSWORD each time it runs; changing POSTGRES_PASSWORD after initialization does not change the superuser's password: rotate it in PostgreSQL and the configuration together.
The database has no host port. The web port binds only to host loopback. PostgreSQL data lives in the named timelines volume, independent of container rebuilds.
docker compose logs -f app
docker compose logs migrate
docker compose down
docker compose up --wait
down preserves saved timelines. down --volumes deletes the database permanently; use it only for disposable environments.
Rebuilding during development
docker compose up --build --wait -d is the correct command for seeing source changes in the container deployment. It builds the editor and Next.js platform together and recreates changed services. Refresh the browser afterward. For faster local frontend development, use npm run dev (or the equivalent pnpm/Yarn command) against PostgreSQL; it watches the editor and runs Next.js development routing. npm start needs a fresh npm run build after source changes.
Public hosting
Set APP_ORIGIN=https://circagraph.org and put an HTTPS reverse proxy on the same host in front of 127.0.0.1:5173. The origin must exactly match the browser URL, without a trailing slash or path. A plain http:// origin other than localhost is refused unless ALLOW_INSECURE_ORIGIN=1, which is meant only for trusted private networks: sessions and passwords then travel unencrypted. Register OAuth providers and set their server-side variables following authentication.md. Desktop clients can connect to that same public origin.
Set TRUST_PROXY=1 only when the proxy overwrites X-Forwarded-For with a single client IP and the application port cannot be accessed directly. Without it, per-address limits such as sign-in count each request under the address it connected from, which under Compose is Docker's gateway for every client, so all visitors share one limit. A proxy running in another container needs a Compose override connecting it to the app's network and forwarding to app:5173; its own loopback will not reach the host-bound port.
Public timelines can be embedded in any site. Set EMBED_FRAME_ANCESTORS to a space-separated list of origins (https://example.org https://*.example.net) to allow only those, or 'none' to allow none.
The sitemap lists the moments and durations of public timelines with at most 5,000 moments. Set SITEMAP_TIMELINE_ENTITIES (1 to 45,000) to change that limit.
To supply an additional plugin catalogue, bind-mount its JSON file into app read-only and set PLUGIN_LIBRARY to its container path. See plugins.md. Setting a host path without mounting it is insufficient.
The export cache is off in Compose unless configured. To keep downloads on disk, mount a volume the app container can write into app and set EXPORT_CACHE_DIR to its path, or set EXPORT_CACHE=s3 and the EXPORT_CACHE_S3_* settings for a bucket.
Upgrades and backups
Back up before upgrading. A plain SQL backup includes the extension declaration, account data, and timelines; restore it into a database with pgmp installed and the application stopped.
docker compose exec -T database pg_dump -U openchronology -d openchronology > openchronology-backup.sql
For an application upgrade, build first, stop the web server, explicitly rerun migrations even if its previous one-shot container has already completed, and recreate the web server:
docker compose build
docker compose stop app
docker compose run --rm migrate
docker compose up --wait --force-recreate app
With the mail worker (--profile mail), recreate it as well, so that it runs the new image: docker compose --profile mail up --wait --force-recreate mail-worker.
If migration fails, leave the web server stopped and inspect its output before continuing. PostgreSQL major upgrades require a separate data migration; do not simply change the image major version against an existing volume. Installations from before APP_DATABASE_PASSWORD existed must add it to .env; Compose refuses to start until they do. docker compose run --rm migrate runs database-setup first, which creates the role and hands it the tables, functions and types the app made while it connected as the superuser.
GitHub CI builds the images, boots an isolated stack, verifies exact pgmp arithmetic and bound queries, checks the HTTP session and static frontend, and round-trips SQLite files using the converter inside the actual web image.
Set FEATURED_TIMELINES in .env to comma-separated public timeline UUIDs for dashboard curation. To open the site on a landing page with pages for each audience, set LANDING_PAGE=1 and the LANDING_EXAMPLES…, LANDING_VIDEO… and LANDING_CONTENT_DIR settings (landing page); a content directory must be mounted into the app service. To tell Bing, Yandex and other engines about changed public timelines within minutes, set INDEXNOW_KEY (IndexNow). The migration service installs full-text search and collaboration tables before starting the app.
Transactional mail and account security
Configure RESEND_API_KEY, AUTH_EMAIL_FROM and a persistent 64-hex-character
AUTH_ENCRYPTION_KEY in .env, verify the sending domain in Resend, then run
docker compose --profile mail up --build --wait -d. This adds the retrying mail
worker to the database, migrations, and web server. Existing installations must
apply migrations before sign-in; existing users must confirm an email address.
Back up the encryption key separately and retain it across rebuilds. See
authentication.md for enrollment, recovery, and DNS setup.