Updating Heaper

Quick update with latest

If your Compose file uses ghcr.io/janlunge/heaper:latest and you just want the newest stable version:

docker compose pull heaper
docker compose up -d heaper

That is all you need. For a rollback-ready update, follow the steps below.

1. Prepare the rollback

In Heaper, open Settings → Servers and note the installed and available versions.

Replace the floating latest or nightly tag in your Compose file with the installed version first:

image: ghcr.io/janlunge/heaper:16.17.19

To roll back, restore this version and recreate the Heaper container:

docker compose pull heaper
docker compose up -d heaper

For Docker Run, repeat your original docker run command with the previous version tag.

Returning to an older image does not undo database migrations. If the old version cannot start, restore the latest pre-update backup.

2. Check the nightly backup

Heaper creates automatic nightly database backups when /mnt/backups is mounted. Check that the newest .sql or .sql.enc file is recent and not empty:

ls -lh ./heaper-data/backups

For Docker Run, check the host directory mounted to /mnt/backups. Do not update if the expected backup is missing.

3. Update Heaper

Replace the installed version with the exact available version shown by Heaper:

image: ghcr.io/janlunge/heaper:16.18.0

Then update the Heaper service:

docker compose pull heaper
docker compose up -d heaper

For separate-container installations, update only the heaper service. Do not change the PostgreSQL image unless the release notes require it.

For Docker Run:

docker pull ghcr.io/janlunge/heaper:16.18.0
docker stop heaper-selfhost
docker rm heaper-selfhost

Then repeat your original docker run command with the new version tag.

4. Wait for migrations

Heaper runs database migrations automatically during startup. Do not stop the container during the first startup after an update.

5. Verify the update

docker compose ps
docker compose logs --tail=100 heaper

Confirm that the service is healthy, Settings → Servers shows the target version, and a workspace and file open normally.