PostgreSQL Docker stack

Runs the backend, dashboard, and PostgreSQL 17 on one Docker host. Artwork and tile objects stay in the objects volume.

Setup

Complete the checkout and common .env settings in Run with Docker. Before starting, generate a database password:

openssl rand -hex 32

Add it to .env:

POSTGRES_PASSWORD=replace-with-the-generated-password

Start the stack:

docker compose -f compose.yaml -f deploy/compose/postgres.yaml up --build -d --wait
docker compose -f compose.yaml -f deploy/compose/postgres.yaml ps

Open http://localhost:3000. The Docker guide shows the initial dashboard and userscript connection steps.

Parameters

Variable	Required	Purpose
`ADMIN_TOKEN`	Yes	Bootstrap administrator token.
`CAELESTIS_READ_TOKEN`	Yes	Separate dashboard read token.
`SEASON`	Set explicitly	The Wplace canvas season.
`POSTGRES_PASSWORD`	Yes	Password for the `caelestis` database user.

The overlay supplies the backend's PostgreSQL host, user, database, and adapter settings. It overrides the example's SQLite selection.

PostgreSQL listens on port 5432 inside the Compose network. The file does not publish that port to the host.

Volumes

Volume	Contents
`postgres`	PostgreSQL database, including progress, tokens, and coordinator state.
`objects`	Template artwork, tile blobs, and social images.
`data`	Backend local files and cache; not the PostgreSQL database.

Back up postgres and objects together. See Storage and backups.

Operations

Use both files for every command:

docker compose -f compose.yaml -f deploy/compose/postgres.yaml logs -f
docker compose -f compose.yaml -f deploy/compose/postgres.yaml down

down keeps the volumes. For updates, follow Deployment and upgrades.

To store artwork in MinIO, add -f deploy/compose/s3.yaml and configure its password. For an existing database managed by CNPG, use CNPG Docker stack.