Upgrading a Self-Hosted Instance

Step-by-step guide for updating Pentographer to a new release on your Docker Compose deployment, including database migration and rollback procedures.

Pentographer releases new versions as Docker images tagged on Docker Hub. Upgrading involves pulling the updated image, restarting the stack, and letting the application run its automatic database migrations.

Before You Upgrade

Check the changelog. Review the GitHub releases page for the new version. Look for any breaking changes to environment variables or migration notes that require manual steps.

Back up your database. Migrations that run automatically cannot be rolled back without restoring a backup. Run a PostgreSQL dump before pulling the new image:

docker compose exec db pg_dump -U postgres pentographer > backup_$(date +%Y%m%d).sql

Store the dump file outside the Docker volume in a location you control.

Upgrading

Pull the latest image and restart the stack:

docker compose pull
docker compose up -d

docker compose pull fetches the updated lswartsenburg/pentographer:latest image without stopping the running containers. docker compose up -d detects the new image and replaces the running container.

On startup, Pentographer automatically applies any pending database migrations using Drizzle ORM. Check the application logs to confirm a clean start:

docker compose logs -f app

Look for the migration completion message before sending traffic to the instance.

Pinning a Specific Version

Running latest means every pull may introduce changes. For production instances, pin to a specific release tag in your docker-compose.yml:

services:
  app:
    image: lswartsenburg/pentographer:1.2.0

To upgrade to a new release, update the tag and run docker compose pull && docker compose up -d.

Rolling Back

If the new version introduces a regression, restore the database backup and revert the image tag:

# Restore database
docker compose exec -T db psql -U postgres pentographer < backup_20260625.sql

# Revert image tag in docker-compose.yml, then restart
docker compose up -d

[!CAUTION] Do not run the application against a database that was migrated to a newer schema version. Always restore the matching backup before reverting the image.

Verifying the Update

After restarting, confirm the running version by checking the application settings page or inspecting the container image:

docker compose images app