Upgrades
Upgrade a running CosmicAC deployment to a new image release.
This guide shows you how to upgrade a running CosmicAC deployment to a new image release.
In-cluster job images upgrade separately
task update upgrades only the Compose platform stack, not the GPU and inference images that run as jobs inside your Kubernetes cluster. Kubernetes pulls those from private GHCR images (interconnect.vmi_image and containerImages.{INFERENCE_VLLM,GPU_CONTAINER}), so Compose's GHCR login doesn't cover them. The cluster needs its own imagePullSecret in the job namespace (for example cosmic-ac-<env>), or public mirrors. To change their versions, bump those tags in the k8s config/common.json, cluster-side.
Upgrade the platform stack
To upgrade the stack, follow these steps.
- Run
task backup. - Set
TAG=<newtag>in.env. - Run
task update. - If the release added config keys, merge them, then run
task restart. - Verify the deployment (see Running CosmicAC). If a worker won't talk, re-run
task wire, then recreate.
To upgrade without editing .env, pass the tag inline in step 3 with task update TAG=<newtag>.
Roll back
Run task update TAG=<previousTag> to roll back to the previous release. State is preserved, but run task backup first for a snapshot.
Upgrade notes
- Config and state stay intact (host bind mounts under
services/<repo>/). compose pullexplicitly refreshes the selected tag. Without it,pull_policy: missingwould keep the stale local image.config-initadds only new config files. You must merge new keys inside existing files by hand. Diff the updatedservices/<repo>/config/*.example.- A normal upgrade resets no state. Public runtime keys appear in
status/, while persistent Hypercore, Autobase, and HyperMQ data lives understore/. Both directories are host bind mounts and survive container recreation. Don't deletestore/during an upgrade. - To scope the upgrade to one service, run
task update TAG=<tag> SERVICES="cosmicac-app-node". The automation includescosmicac-uiand Caddy automatically when app-node is scoped, so the public route is refreshed.