Updates & backups

Pull, restart, done. And the one file that is your entire install.

Updating

Releases are published to ghcr.io/mddanishyusuf/piqo-selfhost with three tags each: the exact version (0.1.3), the minor line (0.1) and the major line (0). The guides pin :0, so pulling again gets every 0.x release and never a breaking major.

Migrations run automatically on boot. On Docker Compose:

docker compose pull
docker compose up -d

On Railway, Render and Coolify, redeploy the service. On Fly, fly deploy. The dashboard shows an “update available” banner when the daily license check-in reports a newer build.

When a 1.0 ships, its notes will say what changed. Move by changing the tag to :1 and redeploying. Take a backup first.

Nightly backups

Every night the app runs SQLite's VACUUM INTO and writes a complete, compacted copy of the database to /app/data/backups/piqo-YYYY-MM-DD.db. The last BACKUP_KEEP_N (default 7) are kept.

Because they live on the same volume, copy them off the box too. From a Docker host:

docker compose cp piqo:/app/data/backups ./piqo-backups

Any object storage sync (rclone, restic, a cron with aws s3 sync) pointed at that folder finishes the job.

Restoring

Each backup file is a full database. To restore, stop the app, replace the live file, start it again:

docker compose stop piqo
docker compose cp ./piqo-backups/piqo-2026-09-06.db piqo:/app/data/piqo.db
docker compose start piqo

If a piqo.db-wal or piqo.db-shm file exists next to it, delete those before starting. They belong to the old database.

Back up AUTH_SECRET with the database. Stored integration secrets are encrypted with it. A restored database under a different secret works, but every payment provider and Search Console connection has to be reconnected.

Retention

By default nothing is deleted. Set DATA_RETENTION_DAYS to have events older than that removed nightly. Hourly and daily rollups are kept, so historical charts still work after the raw rows are gone.

Moving to a new server

  1. Deploy the new install with the same AUTH_SECRET and APP_URL.
  2. Stop the old one, copy its latest backup to the new volume as piqo.db, start the new one.
  3. Point DNS at the new server. Because the hostname is unchanged, the license carries over.
NextTroubleshooting