Upgrading

Containment Chamber ships as a single static binary (or Docker image) with no runtime dependencies. Upgrades replace the binary and restart the process. Schema migrations run automatically on startup.

Before You Upgrade

1. Check the changelog for breaking changes.
2. Back up your current binary or note the Docker image tag you’re running.
3. Verify your anti-slashing database is backed up (PostgreSQL pg_dump or copy the SQLite file).

Upgrade Steps

Bare Metal / systemd

Stop the service, replace the binary, and restart:

# Stop the service
sudo systemctl stop containment-chamber

# Download new binary
curl -L -o containment-chamber \
  https://github.com/unforeseen-consequences/containment-chamber/releases/latest/download/containment-chamber-linux-amd64

chmod +x containment-chamber

# Keep the old binary for rollback
sudo cp /usr/local/bin/containment-chamber /usr/local/bin/containment-chamber.bak

# Install the new binary
sudo install -m 755 containment-chamber /usr/local/bin/

# Restart
sudo systemctl start containment-chamber
sudo systemctl status containment-chamber

Binaries are available for linux-amd64 and linux-arm64. Adjust the download URL accordingly.

Docker

Pull the new image and recreate the container:

# Docker Compose (recommended)
docker compose pull && docker compose up -d

Or with standalone docker run:

docker pull ghcr.io/unforeseen-consequences/containment-chamber:latest
docker stop containment-chamber
docker rm containment-chamber
docker run -d --name containment-chamber \
  -p 9000:9000 -p 3000:3000 \
  -v ./config.yaml:/config.yaml:ro \
  -v ./keystores:/keystores:ro \
  ghcr.io/unforeseen-consequences/containment-chamber:latest \
  -c /config.yaml

Tip

Pin to a specific version tag (e.g. v1.2.0) instead of latest for production. This prevents accidental upgrades when containers restart.

After restarting, confirm the signer is healthy:

curl http://localhost:9000/upcheck
curl http://localhost:9000/api/v1/eth2/publicKeys

Zero-Downtime Upgrades

Containment Chamber has a 25-second graceful shutdown drain. When the process receives SIGTERM, it stops accepting new connections but finishes all in-flight signing requests before exiting. This means brief upgrades with a single instance won’t lose requests that are already being processed.

For true zero-downtime, run multiple instances behind a load balancer:

1. Configure your load balancer to health-check /upcheck.
2. Start the new instance and wait for it to pass health checks.
3. Stop the old instance. The 25-second drain ensures in-flight requests complete.
4. Remove the old instance from the load balancer pool.

Caution

SQLite anti-slashing uses exclusive file locking. You cannot run two instances against the same SQLite database simultaneously. For multi-instance or zero-downtime upgrades, switch to the PostgreSQL anti-slashing backend.

Rollback

If something goes wrong after upgrading, restore the previous version:

Bare Metal

sudo systemctl stop containment-chamber
sudo mv /usr/local/bin/containment-chamber.bak /usr/local/bin/containment-chamber
sudo systemctl start containment-chamber

Docker

# Roll back to a specific version
docker compose down
# Update image tag in docker-compose.yml to the previous version
docker compose up -d

Or pull the previous tag directly:

docker pull ghcr.io/unforeseen-consequences/containment-chamber:v1.1.0

Schema migrations are backward-compatible, so rolling back to a previous binary version won’t cause database issues.

Tip

Always test upgrades on a staging environment or testnet before applying them to your production validators.