Upgrading
Fifteen minutes, most of it waiting for a pull, and the graphs survive it.
The runbook — establishing what you are on, the backup that has no undo, the pull, the verification, and the rollback including the schema half — lives with the code it describes:
→ docs/UPGRADE.md in archgraph-api
What an upgrade touches
| Replaced | the archgraph-api image — API, worker, scheduler and install check all run it |
| Migrated | the Postgres schema, forward only |
| Rebuilt on demand | graphs whose manifest no longer matches the new build |
| Untouched | your environment file, connections, repositories, vault key, graph data, registered webhooks |
Postgres, Neo4j, Redis and Caddy are pinned separately in the compose file. They are not part of an ArchGraph upgrade — bump them deliberately, and not in the same window.
Three things worth knowing before the first one
Ask the install what it is. archgraph-version prints the API
version, the core version and the build sha with no database, no
settings and no network — so it answers on an install that will not
start, which is when the question is usually asked. The same fields are
on /health/detailed and in the image's OCI labels.
Pin the tag. latest names nothing you can return to. Roll forward
by sha, and the rollback is a one-line edit.
Re-indexing is automatic. Each repository's incremental manifest is stamped with the core version, the manifest schema and the set of grammars that produced it. When any of the three differs from the running build, the manifest is discarded and the next run is a full extraction. So the first refresh after a significant upgrade is slower and then things return to normal; nothing needs clearing by hand.
That last pin is not theoretical. A repository indexed while a grammar was missing keeps a manifest listing every file it walked as already seen — so installing the grammar changed nothing until somebody forced a rebuild. The grammar set is the only part of that stamp that can change without a deploy.