Upgrading BugPin

BugPin updates its database automatically when a new version starts, so an upgrade is a backup, a new image or checkout, and a restart. This page covers what to check before any upgrade, the update steps for each installation method, how to choose which releases your installation follows, what to prepare for a major version, and how to roll back.

Release Types

The Admin Console shows administrators a banner when a newer release is available. The banner depends on the type of release:

Release	Example	What to expect
Patch	1.3.0 to 1.3.1	Fixes. A quiet bar with a link to the release notes.
Minor	1.3.0 to 1.4.0	New features. A notice with a link to what's new.
Major	1.3.0 to 2.0.0	Breaking changes. A notice that links to this page and to the release notes.

Not now hides the banner for a day. Closing it hides it for the rest of that release line. Turn the check off under Settings → General with Check for updates.

Before Every Upgrade

1. Read the Before You Upgrade section of the release notes for the version you are upgrading to, and for every minor or major version you skip.
2. Back up the complete data directory, including .secret. A database backup without .secret cannot decrypt authenticator app secrets.
3. Record the version you are running, so you can return to it. About in the Admin Console footer shows it, and so does the health endpoint.

For Docker, also record the exact image digest and keep the previous image available until the upgrade is verified:

docker image inspect "$(docker inspect --format '{{.Image}}' bugpin)" --format '{{json .RepoDigests}}'

If no registry digest is available, retain the local image ID from docker inspect --format '{{.Image}}' bugpin.

For Bun and systemd, record the checked-out commit:

git -C /opt/bugpin rev-parse HEAD

Upgrade Steps

Database migrations run automatically on startup. No manual steps are needed.

Docker

Once the backup is complete, pull and start the new image:

docker compose pull bugpin
docker compose up -d bugpin

Which release this brings in depends on the image tag in docker-compose.yml. See Docker Image Tags.

Bun

# Pull latest changes
git pull origin main

# Install any new dependencies
bun install

# Rebuild
bun run build

Then restart the server.

systemd

# Stop service
sudo systemctl stop bugpin

# Update code
cd /opt/bugpin
sudo -u bugpin git pull

# Install dependencies
sudo -u bugpin bun install

# Rebuild assets
sudo -u bugpin bun run build

# Start service
sudo systemctl start bugpin

# Check status
sudo systemctl status bugpin

Also Upgrade the npm Widget

If any of the sites you embed the widget into use the @arantic/bugpin-widget npm package, upgrade it and redeploy those apps whenever you upgrade the server. The widget and server are versioned independently, so the version numbers do not have to match, but older widget builds can become incompatible with a newer server and silently break report submissions. Check the release notes for the version you are upgrading to: any release that requires a minimum widget version will say so. Sites loading widget.js via a <script> tag are unaffected.

npm install @arantic/bugpin-widget@latest

See Embed the Widget: npm.

Verify the Upgrade

Check that BugPin is running and that the logs show no migration or startup errors.

Docker:

docker compose ps
docker compose logs --tail 50

systemd:

sudo systemctl status bugpin
sudo journalctl -u bugpin -n 50

Also verify sign-in, two-factor authentication or passkeys if configured, existing reports and media, integrations, and a widget submission.

Docker Image Tags

Starting with BugPin 1.3.0, every stable release is published under four tags, so you decide which releases a docker compose pull brings in:

Tag	Follows
1.3.0	Exactly this release. Never changes.
1.3	Patch releases of 1.3.
1	Minor and patch releases of version 1.
latest	Every stable release, including new major versions.

To stay on one major version until you choose to move, set the major tag in docker-compose.yml:

services:
  bugpin:
    image: registry.arantic.cloud/bugpin/bugpin:1

With latest, pulling a new image can start a major upgrade. Read the release notes first.

Major Version Upgrades

A major release can change the database, configuration, and behavior in ways that need preparation. Plan it like a migration:

1. Upgrade to the newest release of your current major version first, and confirm it runs without warnings.
2. Read the release notes of the major version from top to bottom.
3. Take a full backup and verify you can restore it.
4. Upgrade, then verify the installation before reopening access.

Address Warnings in the Admin Console

BugPin 1.3.0 and later check, for administrators, whether BugPin and the browser agree on the address of the installation. A warning appears at the top of the Admin Console when they do not. Future BugPin versions rely on these addresses, so resolve the warnings before a major upgrade.

The Application URL does not match the address you are using. The Application URL under Settings → General differs from the address in your browser. Links in emails and GitHub issues use the Application URL. Set it to the public address administrators use, including the scheme, for example https://bugpin.example.com.

BugPin is behind a reverse proxy but ignores its forwarded headers. Requests arrive with forwarded headers from a proxy that TRUST_PROXY does not trust. This is common when a reverse proxy is added in front of the quick-start docker-compose.yml, which sets TRUST_PROXY=false. Set TRUST_PROXY=auto and recreate the container. If the proxy connects from a public address, the warning asks for TRUST_PROXY=true instead. Use that only when BugPin can be reached through the proxy alone, because it trusts every connecting client. See Client IP Addresses and TRUST_PROXY.

BugPin receives your requests as a different address than your browser uses. The reverse proxy does not pass the original host or protocol. Configure it to send the original Host header and X-Forwarded-Proto, as in the reverse proxy examples.

Not now hides a warning for a day. Closing it hides it in that browser until the addresses change.

Rolling Back

An older BugPin version cannot use a database that a newer version has already updated. Restore the previous version and its matching full data backup together. Running an older version against a migrated database is not a supported rollback.

Docker

1. Stop BugPin with docker compose stop bugpin. Preserve the upgraded data separately; reports submitted after the backup will not be in the restored copy.
2. Restore the complete pre-upgrade backup into the original mount location, including .secret, with the original file ownership and permissions. Restore into an empty directory or volume so upgraded database or journal files cannot be mixed with the backup. Restore the corresponding S3 objects if necessary.
3. Set the Compose image to the exact previous image digest or retained local image ID, then run docker compose up -d --pull never bugpin. Keep that image pinned during recovery so latest cannot select the new release again.
4. Verify the restored installation before reopening access.

For docker run installations, follow the same stop, full-mount backup, and matching-image restore procedure using the container's original options.

Bun and systemd

1. Stop BugPin with sudo systemctl stop bugpin. Preserve the upgraded data directory separately.

2. Restore the complete pre-upgrade backup, including .secret, into an empty data directory.

3. Check out the commit you recorded before the upgrade, then reinstall and rebuild:

   cd /opt/bugpin
   sudo -u bugpin git checkout <previous-commit>
   sudo -u bugpin bun install
   sudo -u bugpin bun run build

4. Start BugPin with sudo systemctl start bugpin and verify the restored installation.

When an Older Version Refuses to Start

Starting with BugPin 1.3.0, the server refuses to start on a database that a newer version has changed, instead of running with a schema it does not understand. The log shows:

This database was changed by a newer BugPin version and cannot be used with BugPin 1.3.0. Migrations unknown to this version: ...

The message lists the migrations it does not know and any pre-upgrade snapshots stored beside the database. To recover, either start the newer version again, or stop BugPin and restore your pre-upgrade backup before starting the older version.

Related

• Backup and Restore
• Docker Installation
• Bun Installation
• Reverse Proxy Setup