Upgrade ReputeCast

To upgrade ReputeCast, you replace the image or binary with a newer release and let it apply its database migrations; everything else (configuration, secret key, data) stays as it is.

See which version you run

An instance admin sees the installed version, the latest release and its changelog under Instance admin › , then Instance & updates, in the Version & updates card. From the command line, reputecast version prints the same: reputecast <version> (<commit>) <Go version>.

• The badge Update available appears when the latest release is newer than the installed version. Builds without a release version number (such as dev) never show it.
• Under Upgrade on the server, the card shows the Docker Compose command cd /opt/reputecast && docker compose pull && docker compose up -d. Replace /opt/reputecast with the folder that holds your docker-compose.yml.
• The switch Check GitHub releases once a day fetches the latest release from api.github.com once a day. The request carries no version number and no instance ID; it is the only outbound call ReputeCast makes on its own. Switch it off here, or set updates.check: false in the configuration to turn it off for the whole instance (the switch is then locked).

Before you begin

• Read the release notes of every version between yours and the new one, on the GitHub releases page.
• Back up the database and the secret key. Migrations change the schema, and a backup is the reliable way back.
• Plan a short interruption while the app restarts.

Upgrade

Docker Compose

1. Go to the folder with your docker-compose.yml and take a backup:

   docker compose exec -T postgres pg_dump -U reputecast -d reputecast -Fc > reputecast-before-upgrade.dump

2. If you pin a version in .env (REPUTECAST_VERSION=v1.4.2), change it to the new release tag. Image tags are the release tags with their leading v, plus latest. Without REPUTECAST_VERSION, the compose file uses latest.

3. Pull the new image and recreate the app container:

   docker compose pull && docker compose up -d

   The image starts with serve --auto-migrate, so it applies pending migrations before it serves requests. The logs show one migration applied line per migration.

Binary

1. Take a backup (see back up and restore).

2. Download the archive for your platform and checksums.txt from the release page, and check the download:

   sha256sum --ignore-missing -c checksums.txt

3. Stop every ReputeCast process, for example sudo systemctl stop reputecast.

4. Replace the binary (for example /usr/local/bin/reputecast) with the new one.

5. Apply the migrations once, with the same environment the service uses:

   reputecast migrate up

   It applies ReputeCast’s migrations, then those of the job queue, and ends with Database is up to date.

6. Start every process again. If you run several roles, upgrade all of them to the same version.

Caution

A process started without --auto-migrate on a database with pending migrations keeps running and only logs database has pending migrations; run `reputecast migrate up` or pass --auto-migrate. Run the migrations before you rely on the new version.

Check that it worked

• Version & updates shows the new version as installed.
• reputecast migrate status lists every migration with an applied date and none as pending. In Docker: docker compose exec app /usr/local/bin/reputecast migrate status.
• /readyz answers ready (health checks, metrics and logs).

Roll back

Going back to the previous image or binary does not undo migrations: the database keeps the newer schema.

• Restore the backup for an exact return to the state before the upgrade: stop ReputeCast, restore the dump you took (see restore), then start the version you ran before. Changes made after the upgrade are lost.
• Pin the previous version (REPUTECAST_VERSION in .env, then docker compose up -d), as the Version & updates card suggests, when you want to keep the data written since the upgrade.
• reputecast migrate down rolls back only the latest ReputeCast migration, one per run, and leaves the job queue’s tables alone. Prefer a restore.

Troubleshooting

• The new container exits at start: read docker compose logs app. A failed migration stops the start with migrate: …; restore the backup and report the error with the release version.
• The version card says the update check failed: the server can’t reach api.github.com, or GitHub answered with an error. Nothing else is affected; the next check runs the following day.
• The latest release shows a dash: the check is off, or has not run yet.

Related

• Back up and restore
• Instance admin: the rest of Instance & updates.
• CLI reference: migrate, version and every other command.