upgrade
Skill7 starsChanged 2 days agoMITView on GitHub
Upgrade the Orbit Docker Compose deployment by rebuilding the apiserver and web images from current source and recreating only changed services; apiserver applies database migrations on boot and unchanged postgres stays running. Use when asked to deploy the latest Orbit code, update or upgrade the running containers, run /upgrade, or bring the Compose deployment up to date. Use --pull-base only when explicitly asked to refresh postgres or gateway base images. With ORBIT_REGISTRY set it is a two-stage release: build, boot-check and push here, then pull and recreate on ORBIT_DEPLOY_HOST, which builds nothing and hands the apiserver and web over without a gap (--stop-then-start for a release whose migration the running code cannot run against); roll back with --deploy <earlier commit>. From a session on another workspace, deploy production through SubAgents on orbit-op (build and deploy) and orbit-prod (check, and move its checkout to the release).
- Reads credentials
32 other projects use a version of this.
Adopted by
Most recently taken up by
- Robo-Co-op/robobuilder-standardtheir own version, first seen Nov 16, 2026
- link7373/agentic-bi-teamtheir own version, first seen Nov 10, 2026
- Mrbaeksang/skillstheir own version, first seen Nov 8, 2026
- roedyrustam/doku-gemini-mcptheir own version, first seen Nov 8, 2026
- aminbadh/workspace-startertheir own version, first seen Nov 1, 2026
- ai-agent-lead/skillstheir own version, first seen Nov 1, 2026
Used with
Projects with it also use new, context and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
codebycoreySkillnew
Start a new change with a proposal. Use when starting a feature, creating a proposal, or beginning planned work.
Also in 4 projects that use this
aegiswizardSkillcontext
Also in 3 projects that use this
MicrosoftSkillinit
Also in 6 projects that use this
AnthropicSkillstatus
Case status summary by audience — client-facing (plain language), internal (for the professor), or court-ready (formal caption format per local rules). Same facts, different framing and depth. Use when a student needs to update the client, brief the professor, or prepare a court status report.
Also in 5 projects that use this
tuistSkillmigrate
Migrates existing Xcode projects to Tuist generated workspaces with build and run validation, external dependency mapping, and migration checklists. Use when adopting Tuist for an existing app or converting a hand-edited Xcode project to generated projects.
Also in 3 projects that use this
imehrSkillfrontend
Use when building UI components, pages, or features - guides Claude through the approved frontend stack (Next.js 15, React 19, Shadcn, Tailwind) with design-first workflow for complex UIs, enforcing patterns and quality standards
Also in 3 projects that use this
Other versions32 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 32
- langwatch/langwatch★ 5ksame name
- agenticnotetaking/arscontexta★ 3.5ksame name
- heyitsnoah/claudesidian★ 2.6ksame name
- TokenRollAI/cc-plugin★ 483same name
- dcb/homeassistant-claude-kit★ 125same name
- rust-off-rails/rustoffrails★ 49same name
- rvdbreemen/adr-kit★ 13same name
- jamillazarev/multica-ops★ 11same name
- ivankuznetsov/llm-wiki★ 9same name
- zauberzeug/game-of-cards★ 7same name
22 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
We split this skill into the rules it gives an agent
4 rules. 0 are common, 2 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 26 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 58
After the migrations, when the image ID is new, it writes that ID into both files, each replaced whole by a rename.
- Distinctive: line 79
After an upgrade, confirm it took effect:
- Very specific: line 135
Run against the checkout the deployment runs from, with the normal deployment environment, including values normally supplied through the …
- Very specific: line 136
Never delete or recreate the orbit_pg volume as part of this workflow.
“Common” is measured: kept by at least 6 in 10 of the 26 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Upgrade the Orbit stack
Orbit uses docker-compose.yml with postgres, apiserver, wiki-worker, web, and gateway. A routine upgrade rebuilds the locally built apiserver and web images (wiki-worker runs the apiserver image), then recreates only changed services. The persisted orbit_pg volume is preserved.
Database migrations are not a separate step: the apiserver container runs prisma migrate deploy during startup.
Workflow
Run in the installed checkout, the one the deployment runs from, and never from a worktree (see "Where to run it" below). Check the current branch, worktree status, and Compose availability. On
mainthe helper runsgit pull --ff-onlybefore building, so the deploy is origin's main and not a stale checkout; it never overwrites or discards local changes and stops if a fast-forward is impossible.The helper refuses to build when tracked files are modified: images are built from the working tree, not from
HEAD, so uncommitted edits reach production while existing in no commit and are silently reverted by the next clean rebuild. Commit or stash first; pass--allow-dirtyonly when deliberately deploying an uncommitted change.Choose flags from the request:
--no-pull: skip the pull onmainand deploy the checkout as it is.--pull: rungit pull --ff-onlyeven when the checkout is not onmain.--pull-base: pull the pinnedpostgresandgatewayimages and recreate the full stack. This is the only mode that may restart postgres; use it only when explicitly requested.--no-cache: rebuild local images without Docker layer cache.--prune: prune dangling images after a successful upgrade.--allow-dirty: build despite uncommitted changes (they exist in no commit).
State which services may be recreated. When the chosen flags match the user's request, run:
.agents/skills/upgrade/scripts/upgrade.sh .agents/skills/upgrade/scripts/upgrade.sh --prune- Report the final
docker compose psstate. If health checks fail, inspectdocker compose logs <service>and diagnose the failure; do not claim the upgrade succeeded.
Behavior
On main the helper first fast-forwards to origin (git pull --ff-only) unless --no-pull is given.
Without --pull-base, the helper:
- Builds
apiserver(whose imagewiki-workerruns) andweb. The web image's downloadable runner is built from the newestv*tag behind HEAD (unpacked at.runner-release/), not from the checkout, so runner code ships only with a release tag (docs/release-process.md, "Runner binaries come from the release tag"); with no such tag, the checkout's own runner is built, with a warning. - Runs
docker compose up -d --wait apiserver wiki-worker web gateway. - Where
docker-compose.override.ymladds other apiservers (apiserver-2and on; docs/self-hosting.md, "Several apiservers"), recreates them onceapiserveris healthy and the migrations are applied, so they find none to apply. - Brings
pgbackupup to date, last (see "pgbackup" below). - Prints
docker compose ps.
Postgres is omitted from the recreate set. With --pull-base, the helper pulls postgres and gateway, then runs a full up -d --wait so changed base images take effect.
The helper writes nothing of managed runners to .env, so they stay as the deployment's .env has them: off unless it switches them on, which only a fresh install (scripts/install-server.sh) or an administrator does (docs/self-hosting.md, "Managed runners"). Where .env does not turn on the managed-runners-docker Compose profile, Compose does not list docker-channel, and the helper builds, recreates and writes exactly what it did before managed runners existed: nothing under data/, no managed runner image.
The helper also brings up the runner link (docs/self-hosting.md, "Runner link"; the section marked in the script, the same in both copies), and what .env says decides what it may do. With no link in it, it builds src/link-gateway, has that image make the link's secrets, and appends them to .env with RUNNER_LINK_URL=same-origin, in one write that changes no line and prints none of them. With RUNNER_LINK_URL=same-origin it rebuilds the gateway, named by the last commit under src/link-gateway, so that a commit elsewhere recreates nothing. With anything else, as production's own host name, .env is not opened for writing, and link-gateway and nats are neither built nor restarted. After the images are built and before the apiserver is recreated, it starts nats and link-gateway, recreates the web gateway if the gateway/nginx.conf it runs is not this checkout's, which Compose does not see, and checks that /runner-link reaches the link gateway. This build's docker-compose.yml requires RUNNER_LINK_SIGNING_KEY, since it has no HTTPS work path, so a failure there stops the upgrade before the apiserver is recreated, and the deployment goes on running the build it has. A pull that changes this script runs the new one, from the start.
Where .env turns that profile on, the helper also keeps managed runners current (the section marked in the script, the same in both copies of /upgrade's script):
- It finds the managed runners' directory where Compose binds it into
docker-channel, and stops before building anything if itschannel.jsonandprofile.jsonare not there. - It builds
docker-channelwith the other images, then the managed runner image fromdeploy/managed-runner/imageasorbit-managed-runner:local(local, never pushed;--no-cacheapplies to it too). - After the migrations, when the image ID is new, it writes that ID into both files, each replaced whole by a rename.
- It recreates the other services as above, then the apiserver again if that did not recreate it (it reads the profile only as it starts), and with it the other apiservers, then
docker-channel, last. The apiserver goes first: until the channel serves the image its profile names, it makes no container and only waits, while a channel already on the new image would refuse the old apiserver's creates.
A managed runner's container keeps the image it was made from and is never stopped by the upgrade: each runner moves to the new image with its next container, when it wakes after it next sleeps. Nothing deletes the previous image while a container uses it: in Docker's containerd image store it loses its name when the new image takes the tag, and its storage goes with the last container made from it; in the classic store --prune removes it once no container, running or stopped, was made from it. data/managed-runners/.image-switch marks a switch written and not yet started on, so a run that failed between the two is finished by the next one.
Concurrent upgrades are serialized with /tmp/orbit-upgrade.lock; a second invocation exits instead of starting another deployment.
Where to run it
Run the helper in the installed checkout, the one the deployment runs from, and never from a worktree. A deployment's bind mounts are relative (./data/postgres, ./data/pg-archive, ./data/files), so from any other directory Compose would bind that directory's empty ./data: the database, the archive the off-host mirror reads, and every attachment's bytes.
So the helper stops first, before it pulls, builds, tags or recreates anything, if the postgres container this checkout's Compose names has its /archive anywhere else. The refusal names the checkout to run from and says nothing was changed. With no such container there is no deployment yet, and a first install goes ahead. A separate deployment on the same Docker passes on its own /archive if its containers have names of their own, set in its docker-compose.override.yml, and it exports its own COMPOSE_PROJECT_NAME for this helper: the check goes by the name Compose renders, so one with the same names cannot be told from that deployment and is refused.
pgbackup
The backup sidecar needs a step of its own. Compose bind-mounts scripts/pg-backup.sh into it as a single file, so a new checkout replaces the file under a running container, which keeps the one it started on, and Compose sees no change. The helper compares what the container has with the checkout: if they differ it runs docker compose up -d --wait --no-deps --force-recreate pgbackup, otherwise the same without --force-recreate, which recreates it for a change of configuration, such as a new mount, and leaves it running if there is none. --no-deps keeps postgres out of it, and recreating it cuts short a base backup in progress, which it takes again as it starts.
A sidecar that is not running is left as it is, and the helper says pgbackup was NOT updated as its last lines, with the command to run.
The step is in the script, so it runs once the script on disk has it. A run from an older version pulls the new script from inside itself and finishes as the old one, reporting success with pgbackup unchanged. Put the new version on disk first and pass --no-pull, or run it a second time.
After an upgrade, confirm it took effect:
# The mount, read-only: prints "/var/lib/orbit/files false".
docker inspect orbit-pgbackup --format '{{range .Mounts}}{{println .Destination .RW}}{{end}}' | grep /var/lib/orbit/files
# The script is this checkout's: prints nothing, and exits 0.
docker exec orbit-pgbackup cat /usr/local/bin/pg-backup.sh | cmp - scripts/pg-backup.sh
# Both copies are named and working: "watching" names <target> and <target>-files, with no ERROR after it.
docker logs orbit-pgbackup 2>&1 | grep -E 'watching|mirrored|ERROR' | tail
# A file from ./data/files reached the target, within a poll (15 minutes) of the sidecar starting. With
# ORBIT_BACKUP_SYNC_TARGET=root@backup-host:/data/backup/orbit-pg-archive:
f="$(find data/files -type f -not -path 'data/files/tmp/*' | tail -1)"
ssh root@backup-host ls -l "/data/backup/orbit-pg-archive-files/${f#data/files/}"With no ORBIT_BACKUP_SYNC_TARGET, or with ORBIT_FILES_BACKEND=s3, the last two have nothing to show: see the backup and restore runbook, docs/postgres-backup-restore.md, "Attachment files".
Two-stage release
With ORBIT_REGISTRY set, the helper builds on this host and deploys on another, which runs the deployment and builds nothing: Orbit's production builds on wikova, pushes to the WireGuard-only registry 10.66.0.1:5000, and runs on 10.66.0.4. Without ORBIT_REGISTRY nothing here applies. The full account is the .claude skill's section of the same name (.claude/skills/upgrade/SKILL.md).
ORBIT_REGISTRY=10.66.0.1:5000 ORBIT_DEPLOY_HOST=root@10.66.0.4 .agents/skills/upgrade/scripts/upgrade.sh --prune
ORBIT_REGISTRY=10.66.0.1:5000 .agents/skills/upgrade/scripts/upgrade.sh --build-only
ORBIT_REGISTRY=10.66.0.1:5000 ORBIT_DEPLOY_HOST=root@10.66.0.4 .agents/skills/upgrade/scripts/upgrade.sh --deploy <40-character commit>
ORBIT_REGISTRY=10.66.0.1:5000 ORBIT_DEPLOY_HOST=root@10.66.0.4 .agents/skills/upgrade/scripts/upgrade.sh --plan <40-character commit>
ORBIT_REGISTRY=10.66.0.1:5000 ORBIT_DEPLOY_HOST=root@10.66.0.4 .agents/skills/upgrade/scripts/upgrade.sh --deploy <40-character commit> --stop-then-startORBIT_DEPLOY_DIR is the deployment's directory on the target (/root/orbit). After the lock, the dirty check and the pull, deploy/two-stage/release.sh takes over, and this host's own containers, .env and runner link are left as they are.
- Build stage, here: the images are tagged by commit,
<registry>/orbit-apiserver:<commit>,<registry>/orbit-web:<commit>and<registry>/orbit-link-gateway:<last commit under src/link-gateway>. Each that is not in the registry yet is built (docker compose build apiserver wiki-worker web, keeping the target's serving web release at/dl/previous/throughorbit-web:previous-release; the link gateway withdocker build --provenance=false), booted byscripts/image-boot-check.sh, and pushed. A tag in the registry is never pushed again. - Deploy stage, on the target over ssh: the target has no checkout. The commit's
docker-compose.yml,gateway/,scripts/pg-archive-wal.sh,scripts/pg-backup.sh,src/link-gateway/nats.conf,deploy/runner-link/,deploy/postgres-pinned.yml,deploy/db-proxy.ymlanddeploy/db-proxy/are shipped withgit archive, anddeploy/two-stage/deploy-stage.shtakes the target's/tmp/orbit-upgrade.lock, puts the files in place (and back, with no directory it added, if it stops before its images are all pulled), prints each service's config-hash plan (withdb-proxy,gatewayandpgbackupalsorecreatewhen the single file each bind-mounts is not the release's), refuses an image that does not come from the registry, pulls every image, writes the release into its block of the target's.env, and brings each service up withdocker compose up -d --wait --no-deps --no-buildindepends_onorder: postgres, db-proxy, nats, apiserver and the rest. A running postgres is recreated only with--pull-base. Its log and history are in.upgrade/there. - Without a gap, the default: the apiserver and web it recreates are handed over.
<name>-next, a container of the release (docker compose run --no-deps; the apiserver's with--use-aliases, so the link gateway reaches it too), starts beside the running<name>and, once healthy, gets the web gateway's traffic:gateway/nginx.conf's routes include a file from/etc/nginx/handover/, which the deploy writes inside the running gateway beforenginx -tand a reload. Then<name>stops by itself (an apiserver exits 0 within 25 s),uprecreates it, the gateway is pointed at it, and<name>-nextstops and is removed. The apiserver's-nextapplies the migrations as it starts.wiki-workeris simply recreated. A gateway the release recreates goes first, a moment's break of its own. Streams end when their apiserver stops and the clients open them again from the last stored event; a reload closes the gateway's idle keep-alive connections, as every nginx reload does. - The plan says which way:
Replacing the apiserver and web: without a gap, orstop, then startwith the reason:--stop-then-start, a release whosegateway/nginx.confpredates handovers (a rollback to one), or no gateway running. Stop, then start is how every release did it before: the web gateway answers 502 until each new one is healthy, 20 to 40 s for the apiserver. - Migrations, the exception: during a handover the running release's code runs against the database as the new release's migrations leave it. A migration that code cannot run against (it drops or renames a table or column the old code uses, adds a
NOT NULLcolumn without a default where it inserts, or a constraint or trigger its writes break) is deployed with--stop-then-start. Additive migrations need nothing. Compare the release with the commit the target runs, the last line of its.upgrade/history:git diff --stat <running> <release> -- src/apiserver/prisma/migrations/. - A deploy that did not finish can leave
<name>-nextrunning with the gateway on it: the next deploy puts the gateway back and removes it once<name>is healthy, and otherwise stops and says to deploy with--stop-then-start. A-nextthat has not passed its health check is never stopped, since it may be applying the migrations. --plan <commit>runs the deploy stage up to its plan and the registry check, then puts every file back: it pulls, writes and brings up nothing.- The target's
.envis its own, made once before the first deploy; a deploy writes only the block between# >>> The release this host runsand# <<< The release this host runs, so a laterdocker composethere renders the release that runs. ItsCOMPOSE_FILElistsdocker-compose.yml:deploy/postgres-pinned.yml, and:deploy/db-proxy.ymlwhere the apiserver connects through the proxy (10.66.0.4's does); the release ships those. Any other Compose file it lists, or itsdocker-compose.override.yml, is rendered with each release and otherwise left alone. - Base images run by digest: postgres and pgbackup as
deploy/postgres-pinned.ymlpins them (PostgreSQL 16.14), db-proxy asdeploy/db-proxy.ymldoes, nginx and nats asdeploy/two-stage/base-images.envdoes. A target that does not listdeploy/postgres-pinned.ymlis refused. - Rollback:
--deploy <earlier commit>, which builds nothing (--plan <earlier commit>first shows what it changes); the target's.upgrade/historylists what it ran. Code older than a migration the database has applied may not run on it. - Both hosts' Docker must trust the registry (
insecure-registriesin/etc/docker/daemon.jsonfor a plain-HTTP one, applied withsystemctl reload docker).docker buildx duanddocker image lson the target show that nothing was built there.
Production from another workspace
Production spans two workspaces, each a git checkout of this repository at /root/orbit. orbit-op is wikova, where the two-stage release is built and driven from, always in a fresh /dev/shm/wkdir-release-main-<commit> worktree, never in its shared /root/orbit. orbit-prod is 10.66.0.4, whose /root/orbit is the deploy directory, detached at the commit it runs. A session on another workspace runs nothing locally. Once the owner has asked for the deploy in that session, it:
- names the commit (
git fetch origin main && git rev-parse origin/main, unless the owner named one); - calls
delegate({ workspace: "orbit-op", background: true, size: "M", ... })with the orbit-op brief and ends its turn until Orbit wakes it with the result (a session on orbit-op deploys itself instead); - on
✓ Release <commit> runs on root@10.66.0.4, callsdelegate({ workspace: "orbit-prod", size: "S", ... })with the orbit-prod brief, which checks production on the host and moves its checkout to the release.
Both briefs are in .claude/skills/upgrade/SKILL.md, "Production from another workspace". A result without that line is not a deploy.
Requirements
- Docker Compose v2 is preferred. The legacy
docker-composebinary is a fallback, but--waitrequires v2 support. - Run against the checkout the deployment runs from, with the normal deployment environment, including values normally supplied through the root
.env. - Never delete or recreate the
orbit_pgvolume as part of this workflow.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

