Upgrading the web app

The frontend is a stateless container. There is no volume and no database migration, so an upgrade is a container swap and a rollback is a rename. These steps assume the production topology: the container bound to 127.0.0.1:8080, with host nginx serving the public origin and handling /api and /collect. In that shape the container joins no Docker network and needs no --add-host. Use an immutable version tag, not latest.

Upgrade

Pull the version you intend to deploy:

VERSION=v1.0.1
docker pull "ghcr.io/tofunmiadewuyi/custos-frontend:${VERSION}"

Copy the running container’s environment into a temporary root-only file. Drop the old CUSTOS_APP_VERSION override — the new image already carries its own build version:

sudo install -m 600 /dev/null /root/custos-frontend.env

docker inspect custos-frontend \
  --format '{{range .Config.Env}}{{println .}}{{end}}' \
  | grep -v '^CUSTOS_APP_VERSION=' \
  | sudo tee /root/custos-frontend.env >/dev/null

Keep the old container around, stopped, so rollback stays cheap. Then start the new image with the same runtime configuration:

docker stop custos-frontend
docker rename custos-frontend custos-frontend-old

sudo docker run -d \
  --name custos-frontend \
  --restart unless-stopped \
  --env-file /root/custos-frontend.env \
  -p 127.0.0.1:8080:8080 \
  "ghcr.io/tofunmiadewuyi/custos-frontend:${VERSION}"

sudo shred -u /root/custos-frontend.env

The env file is shredded because it carries the full runtime configuration of a live deployment. It holds no secrets by design, but it does not need to persist on disk either.

Verify the container and the public route:

docker logs --tail=100 custos-frontend
curl http://127.0.0.1:8080/healthz
curl https://custos.example.com/healthz

Once verified, remove the old container:

docker rm custos-frontend-old

Roll back

While custos-frontend-old still exists:

docker rm -f custos-frontend
docker rename custos-frontend-old custos-frontend
docker start custos-frontend

Getting started

Concepts

Control plane

Hosts

Web app

Guides

Operations

Reference

Internals

Upgrading the web app

Upgrade

Roll back

​Upgrade

​Roll back

Upgrade

Roll back