Skip to main content

Updating

docker compose pull && docker compose up -d

That is the whole update. pull fetches any newer images; up -d recreates the containers that changed and leaves the rest alone. Database migrations run when the api container starts, so there is no separate migrate step to remember. This is the same command covered in Operating; this page adds what happens underneath and how to pin a version.

What happens on the api's first boot after an update​

The new api container runs its startup sequence before it serves traffic. It checks the platform database is reachable, applies any pending platform migrations, loads the installed modules, and then reconciles each workspace's schema (a module that shipped a new migration since a workspace enabled it gets caught up here). Only after that does it start listening.

If a migration fails, the boot fails on purpose. A half-migrated database is worse than an api that is briefly down, so Cobblr would rather stop loudly than serve against a schema it only half-changed. The container's healthcheck gives this startup a 60-second grace period before it counts as unhealthy, which is enough for the migration and module-load work above. A boot that stays unhealthy past that is telling you the update did not apply cleanly; see Rollback.

Choosing a channel​

By default the images track latest. COBBLR_VERSION in your .env points every service at a different tag instead:

# .env
COBBLR_VERSION=nightly

nightly is the development channel, carrying what landed the day before. Most days there is a new one; a quiet day, or a build that does not come out clean, means there isn't. Track it if you want changes as they land and do not mind the occasional rough edge.

Most people should stay on latest, which follows numbered releases. The same setting pins one exactly:

# .env
COBBLR_VERSION=2026.8.0

Versions are dated rather than semantic: the year, the month, then a counter within that month. Pinning is how you control when you move, and it is the same lever Rollback uses to step back to a known-good version.

Either way, docker compose pull && docker compose up -d then pulls exactly that tag for every service.

After the update​

Open the app and check the environment chip in the interface: it reads the running build from the api's health endpoint, so a stale tab can tell it is behind. If something looks off, Health and status shows how to read the health endpoint and the container state directly.