Upgrading

KubeWatch follows semantic versioning. Minor and patch releases are safe to apply with a rolling restart. Major version upgrades may require a database migration, check the release notes first.

Standard upgrade (Docker Compose)

cd /opt/kubewatch

# 1. Pull the latest images
docker compose pull

# 2. Restart services with new images (rolling, one service at a time)
docker compose up -d

Docker Compose will restart each service with the new image. Services that haven't changed will not be restarted.

Check current versions

cd /opt/kubewatch
docker compose images

Sample output:

SERVICE       REPOSITORY                                              TAG     IMAGE ID       SIZE
auth          ghcr.io/lloyd-theophilus/monitoring/auth                1.4.2   abc123def456   45MB
gateway       ghcr.io/lloyd-theophilus/monitoring/gateway             1.4.2   def456abc123   12MB
ingestion     ghcr.io/lloyd-theophilus/monitoring/ingestion           1.4.2   ...

Database migrations

Database schema migrations run automatically when a service starts. You do not need to run migrations manually. If a migration fails, the service will exit with a non-zero code, check its logs:

docker compose logs auth
docker compose logs query

Pinning to a specific version

To prevent automatic upgrades to the latest tag, pin each service to a specific version in docker-compose.yml:

services:
  gateway:
    image: ghcr.io/lloyd-theophilus/monitoring/gateway:1.4.2

Then upgrade by changing the version numbers and running docker compose up -d.

Rollback procedure

If an upgrade causes issues:

cd /opt/kubewatch

# 1. Stop current services
docker compose down

# 2. Check out the previous release tag
git fetch --tags
git checkout v1.4.1  # replace with the version you're rolling back to

# 3. Start with the previous version's images
docker compose pull
docker compose up -d

Upgrade checklist

Before upgrading:

• Read the release notes for any breaking changes
• Back up your database (docker compose exec postgres pg_dump ...)
• Take a VM snapshot if running on a cloud VM
• Schedule the upgrade during a low-traffic window
• Verify all agents are connected and reporting before upgrading