Skip to content

Upgrades

Walter upgrades should use pinned image tags and an explicit migration step before the new app version takes traffic.

Docker Compose bundle

From the bundle directory, update .env.deploy with the new tag and then run:

bin/selfhost-compose --mode public-tls pull
bin/selfhost-compose --mode public-tls run --rm setup
bin/selfhost-compose --mode public-tls up -d

If you are on internal-tls, swap the mode flag accordingly.

Re-run the installer

You can also reuse the installer to update the configured image tag:

cd ~/walter-selfhost
bin/selfhost-install --mode internal-tls --host walter.internal.example --image ghcr.io/matchylabs/walter:0.1.1

That updates WALTER_IMAGE, validates registry access, and restarts the stack.

Migration-blocked mode

If Walter starts before the database schema is updated, it enters a safe blocked state:

  • browser traffic redirects to /migration-required
  • API traffic returns 503
  • /health/live still returns 200
  • /health and /health/ready return 503

This protects operators from serving a code and schema mismatch.

Backups

Before a production upgrade, back up both:

  • the PostgreSQL data volume
  • the walter_state volume that stores generated bootstrap secrets and local state