Backup and Restore
Everything BugPin stores lives in one data directory: the SQLite database, uploaded files, and the instance key. A backup is a copy of that directory taken while BugPin is stopped. This page covers what to include, the commands for Docker and for Bun or systemd installations, and how to move BugPin to another server.
What to Back Up
Back up the complete data directory, not only the database:
data/
├── bugpin.db # SQLite database (all reports, users, settings)
├── .secret # Auto-generated key that encrypts authenticator app secrets
└── uploads/ # User-uploaded files
├── screenshots/ # Bug report screenshots
├── attachments/ # File attachments
└── branding/ # Custom logo and branding assets
- Include the SQLite journal files next to
bugpin.dband the hidden.secretfile. The secret is required to decrypt authenticator app secrets. Without it, authenticator apps stop working and users must sign in with a recovery code. - Keep your configuration with the backup:
docker-compose.yml, any.envfile, the systemd service file if you changed it, and the reverse proxy configuration. - S3 storage (Enterprise Edition): stored objects are not in the data directory. Back them up separately.
- Protect backups as credentials and keep a copy outside the host. See Backup Security.
The data directory is /data inside the container for Docker, mounted from ./data or a named volume. For Bun and systemd it is ./data relative to where BugPin runs, for example /opt/bugpin/data. See Data Persistence.
Back Up
Stop BugPin before copying its data, so the database is not written to during the copy.
Docker
For bind mounts (default):
# Stop the container
docker compose stop bugpin
# Backup the data directory
tar -czf bugpin-backup-$(date +%Y%m%d).tar.gz ./data
# Restart
docker compose start bugpin
For named volumes:
# Stop the container
docker compose stop bugpin
# Backup the named volume
docker run --rm \
-v bugpin-data:/data \
-v "$(pwd):/backup" \
alpine tar -czf /backup/bugpin-backup-$(date +%Y%m%d).tar.gz /data
# Restart
docker compose start bugpin
For a custom bind mount or named volume, substitute the actual /data mount. Do not remove the volume. If the backup fails, restart the existing container with docker compose start bugpin and resolve the failure before upgrading.
Bun and systemd
The commands assume BugPin is installed in /opt/bugpin and runs as the bugpin service, as in the systemd guide. Adjust the path if your data directory is elsewhere.
# Stop the service
sudo systemctl stop bugpin
# Backup the data directory
sudo tar -czf bugpin-backup-$(date +%Y%m%d).tar.gz -C /opt/bugpin data
# Restart
sudo systemctl start bugpin
Without systemd, stop the bun run start process before copying the directory.
Restore
Restore into an empty directory or volume, so files from the current installation cannot mix with the backup. Restoring replaces all current data: reports submitted after the backup was taken are not in it.
Docker
For bind mounts:
docker compose down
rm -rf ./data
tar -xzf bugpin-backup-20260103.tar.gz
docker compose up -d
For named volumes:
docker compose down
docker volume rm bugpin-data
docker volume create bugpin-data
docker run --rm \
-v bugpin-data:/data \
-v $(pwd):/backup \
alpine tar -xzf /backup/bugpin-backup-20260103.tar.gz -C /
docker compose up -d
If the container cannot write to a restored bind mount, fix the ownership. See File Permissions for Bind Mounts.
Bun and systemd
sudo systemctl stop bugpin
# Keep the current data aside instead of deleting it
sudo mv /opt/bugpin/data /opt/bugpin/data.before-restore
sudo tar -xzf bugpin-backup-20260103.tar.gz -C /opt/bugpin
sudo chown -R bugpin:bugpin /opt/bugpin/data
sudo systemctl start bugpin
To restore a backup taken before an upgrade, also return to the BugPin version that created it. See Rolling Back.
Move to Another Server
Moving BugPin is a backup on the old server and a restore on the new one.
Docker with a bind mount (easiest):
# On old server
docker compose down
tar -czf bugpin-full.tar.gz docker-compose.yml data/
# Copy to new server
scp bugpin-full.tar.gz user@newserver:/opt/bugpin/
# On new server
tar -xzf bugpin-full.tar.gz
docker compose up -d
For named volumes or Bun installations, take a backup as described above, install the same BugPin version on the new server, and restore the backup there before the first start.
After the move, update the reverse proxy and DNS to point to the new server, and check the Application URL under Settings → General if the address changed.