Skip to content

Upgrades

Walter On-Prem upgrades are CLI-first. The CLI stores the deployment mode in .env.deploy, refreshes the bundle safely, and resolves supported release targets from the public release manifest.

Check available targets

cd ~/walter-onprem
bin/walter-onprem versions

That reads https://onprem.walterops.com/releases/manifest.v1.json and shows:

  • the latest stable Walter release
  • the latest patch release for each supported major.minor series
  • upgrade note links for the published releases

Normal upgrade paths

# Latest patch in the current series
cd ~/walter-onprem
bin/walter-onprem upgrade

# Latest supported minor release
cd ~/walter-onprem
bin/walter-onprem upgrade --minor

# Exact release from the manifest
cd ~/walter-onprem
bin/walter-onprem upgrade --to <supported-release>

# Exact image when you need to bypass the manifest
cd ~/walter-onprem
bin/walter-onprem upgrade --image ghcr.io/matchylabs/walter:<supported-release>

What upgrade does

Every upgrade run:

  1. Resolves the requested Walter image
  2. Downloads and verifies the current on-prem bundle
  3. Moves the existing ~/walter-onprem directory to a timestamped backup
  4. Unpacks the new bundle into a clean ~/walter-onprem
  5. Restores the previous .env.deploy
  6. Writes any requested host or mode changes
  7. Pulls the new image and restarts the stack

This means upgrades no longer depend on operators remembering which files are bundle-managed and which ones are safe to edit in place. It also means walter-onprem will refuse to refresh a non-empty directory that does not already look like a Walter On-Prem install unless you pass --force.

Changing the hostname or mode

Mode and hostname are treated as deployment state, not repeated boilerplate. If you want to change them intentionally, pass them on the upgrade:

cd ~/walter-onprem
bin/walter-onprem upgrade --mode public-tls --host walter.example.com --minor

If you omit --host, the CLI keeps the current PHX_HOST.

For bundle-managed internal-tls installs, you can also change the published host ports during upgrade:

cd ~/walter-onprem
bin/walter-onprem upgrade --mode internal-tls --host 192.168.1.50 --https-port 8443

public-tls continues to require standard public 80/443.

Older experimental installs

Older selfhost-named installs are not upgraded in place by the new CLI. This operator surface is a hard cut:

  • current supported install dir: ~/walter-onprem
  • current supported command surface: bin/walter-onprem ...
  • current supported release metadata: /releases/manifest.v1.json

If you still have an older ~/walter-selfhost directory from earlier experiments, treat the move to walter-onprem as a fresh install and only carry old data forward if you explicitly still want it.

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