Update the Watchflare Hub

Before you update

Take a database backup before every upgrade. Schema migrations run automatically on startup and are not reversible without a backup:

docker exec watchflare-postgres pg_dump -U watchflare watchflare > watchflare-pre-update.sql

If you are running the binary install with an external TimescaleDB, use pg_dump directly:

pg_dump -h localhost -U watchflare watchflare > watchflare-pre-update.sql

Check the changelog to review what changed in the new version before updating.

Docker

Pull and restart

docker compose pull
docker compose up -d

$ docker compose pull
[+] Pulling 2/2
✔ watchflare Pulled
✔ postgres   Pulled

$ docker compose up -d
[+] Running 2/2
✔ Container watchflare-postgres  Started
✔ Container watchflare           Started

The Hub runs database migrations automatically on startup. No manual steps are needed.

Verify

Check that the new container started cleanly:

docker compose ps
docker compose logs watchflare --tail 30

Look for a line like Hub started in the logs. If migrations ran, they will appear before this line. Open the dashboard to confirm it is reachable and hosts and metrics are intact.

Pinning a version

By default, docker-compose.yml uses the latest tag. To pin to a specific release, edit the image tag:

services:
  watchflare:
    image: ghcr.io/watchflare-io/watchflare:0.38.0

Then pull and restart:

docker compose pull
docker compose up -d

Pinning is recommended in production so that automated image pulls do not trigger unexpected updates.

Rolling back (Docker)

Downgrading is not supported. Migrations are additive and forward-only — running an older image against a migrated database may fail or produce unexpected behavior.

If you need to roll back, restore from the backup taken before the upgrade:

# Stop the Hub
docker compose down

# Restore the database
docker compose up -d watchflare-postgres
docker exec -i watchflare-postgres psql -U watchflare watchflare < watchflare-pre-update.sql

# Pin to the previous image version in docker-compose.yml, then start
docker compose up -d

Binary (Linux — systemd)

Replace the binary

Stop the service, download the new binary, and restart:

sudo systemctl stop watchflare-hub

TAG=v0.38.0
VERSION=0.38.0
ARCH=amd64    # or arm64

curl -L "https://github.com/watchflare-io/watchflare/releases/download/${TAG}/watchflare-app_${VERSION}_linux_${ARCH}.tar.gz" \
  | tar xz
sudo mv watchflare-app /usr/local/bin/

sudo systemctl start watchflare-hub

Verify

sudo systemctl status watchflare-hub
journalctl -u watchflare-hub --since "1 minute ago"

Look for Hub started in the logs. The binary runs embedded migrations automatically on startup.

Rolling back (binary)

Stop the service, restore the database backup, reinstall the previous binary, and restart:

sudo systemctl stop watchflare-hub

# Restore the database — use psql directly, or docker exec if TimescaleDB is in Docker
psql -h localhost -U watchflare watchflare < watchflare-pre-update.sql
# docker exec -i watchflare-postgres psql -U watchflare watchflare < watchflare-pre-update.sql

# Reinstall the previous binary version (same download command, with the old tag)
TAG=v0.35.0   # the version you are rolling back to
VERSION=${TAG#v}
ARCH=amd64
curl -L "https://github.com/watchflare-io/watchflare/releases/download/${TAG}/watchflare-app_${VERSION}_linux_${ARCH}.tar.gz" \
  | tar xz
sudo mv watchflare-app /usr/local/bin/

sudo systemctl start watchflare-hub

Agent compatibility

Agents do not need to be updated at the same time as the Hub. The Hub maintains backwards compatibility with older agents across minor versions. Check the changelog for any breaking changes that affect the agent protocol.

Agents update independently. See Update the Agent.

To review or change Hub environment variables after an update, see the Hub configuration reference.