Backups and upgrades
Keep database records and uploaded files together when backing up.
Before an upgrade
- Read the release notes for the version you plan to install.
- Ask GMs to save active games and have players leave their rooms.
- Back up PostgreSQL and the uploaded asset directory or volume.
- Keep the existing configuration and password files securely.
Database records refer to uploaded files, so restoring only one side can leave an incomplete installation. Stop application writes while taking a matching database and asset backup. Test restoration on a separate instance.
What to back up
| Installation | Database | Uploaded files |
|---|---|---|
| Docker Compose | PostgreSQL in db-data |
The assets volume |
| Direct Node.js | Your configured PostgreSQL database | ASSETS_DIR, default ./saved-assets |
| Native Linux or Proxmox | PostgreSQL on the host or container | /var/lib/open-tabletop/assets or its mounted storage |
Use PostgreSQL backup tools or your database provider's supported backup method. Copying a
live database data directory is not a substitute for a consistent database backup. Native
installer updates create dumps under /var/backups/open-tabletop/, but
uploaded assets still need a separate backup.
The generated .texture-cache/v1 directory can be rebuilt from originals.
Preserve the original uploads. Redis stores temporary rate-limit state, not game saves.
Upgrading an older secret-based configuration
When moving from a pre-0.10 Compose configuration, create the database secret files from
the existing DB_PASSWORD and APP_DB_PASSWORD values, not new
random passwords. npm run secrets:migrate copies them without printing them
and refuses to overwrite existing files. Create the administrator password file separately
and keep all mounted secrets readable by the container account. Existing PostgreSQL
volumes retain their current role passwords.
Update Docker Compose
For installations using a published image, set the intended version in the Compose file and run:
docker compose pull
docker compose up -d
For installations building from source, select the intended source revision and run:
docker compose up -d --build
Keep the existing database and asset volumes. Do not replace password files with newly generated values: the database keeps its existing role passwords.
Update a direct Node.js installation
Stop the app, select the intended source revision, run npm ci, and restart
using your normal service manager or npm start. Keep .env and
uploaded assets. Apply the release's migrations manually if automatic migration is
disabled.
Update native installs
The Linux and Proxmox guides document their update commands, release directories, and backup locations. Their installers do not upgrade PostgreSQL major versions.
Migrations and rollback
With automatic migration enabled, the app applies pending numbered SQL migrations at startup using its separate owner connection. The runtime connection remains restricted. If you manage migrations yourself, apply every pending migration in order for the target version.
Database migrations may not be reversible. Roll back using the matching database backup, uploaded assets, and application revision.
After an upgrade
Refresh browser clients. Verify administrator login, an asset upload, two-player room access, and a saved game's hands and turn. Account recovery in current source requires migration 023; published 0.20.0 upgrade notes cover migration 022. Match the instructions to the source or release you deploy.
See the release guide for version-specific details.
Sources checked: docs/RELEASING.md, CHANGELOG.md, proxmox/install.sh. Reviewed September 29, 2026 against the working source. Published releases may differ; check the changelog for your version.