> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tofunmiadewuyi.com/custos/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrading the web app

> Swap the frontend container for a new image tag, and roll back.

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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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
```

<Note>
  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.
</Note>

Verify the container and the public route:

```bash theme={null}
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:

```bash theme={null}
docker rm custos-frontend-old
```

## Roll back

While `custos-frontend-old` still exists:

```bash theme={null}
docker rm -f custos-frontend
docker rename custos-frontend-old custos-frontend
docker start custos-frontend
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.