Skip to content

docs(deployment): spell the tag scheme with metavariables, and teach check:docs-image-tag to see prose#10256

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
os-zhuang merged 3 commits into from
Aug 20, 2026
+497 −24
Merged

docs(deployment): spell the tag scheme with metavariables, and teach check:docs-image-tag to see prose #10256

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
99831b4
docs(deployment): the tag scheme is spelled with metavariables, and t…
claude Aug 20, 2026
cbb17b8
fix(scripts): the docs-image-tag scope line states what was scanned, …
claude Aug 20, 2026
b881249
docs(scripts): re-measure the historical-sentence count the gate head…
claude Aug 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions content/docs/deployment/index.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -11,7 +11,7 @@ Two different things get deployed here, and they run on **separate clocks**:
|:---|:---|:---|
| The sentence that fits | "I operate ObjectStack." | "I build an app that runs on it." |
| Ships as | a Docker image (or the `os` CLI on a host) | a compiled artifact, `dist/objectstack.json` |
| Versioned by | our release train (`17.0.0`) | your own catalog |
| Versioned by | our release train (`X.Y.Z`) | your own catalog |
| Whose cadence | ours | yours |
| The deploy action | move the image tag, restart | compile, then install it or pin it at boot |
| Rolling back | restore the previous tag or artifact | install the previous version |
Expand DownExpand Up@@ -39,8 +39,9 @@ jobs, two cadences, two checklists. Read the one you are acting on today.
The platform ships as a single version-locked train: every `@objectstack/*`
package shares one version number, and that number is the platform version. It
is published as an official runtime image, `ghcr.io/objectstack-ai/objectstack`,
whose tags mirror `@objectstack/cli` versions (`17.0.0`, `17.0`, `17`,
`latest`). Pin the exact version in production and move it deliberately.
whose tags mirror `@objectstack/cli` versions: the exact `X.Y.Z`, plus the
rolling `X.Y`, `X` and `latest` tags. Pin the exact version in production and
move it deliberately.

### Where it runs

Expand Down
9 changes: 6 additions & 3 deletions content/docs/deployment/self-hosting.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -56,9 +56,12 @@ itself ships: ObjectStack builds and publishes an **official runtime image**
on every framework release — `ghcr.io/objectstack-ai/objectstack`, Node 22 +
`@objectstack/cli` + `os start`, running as a non-root user with a built-in
health check and `OS_ARTIFACT_PATH` / `OS_PORT=8080` preset. Image tags mirror
`@objectstack/cli` versions (`17.0.0`, `17.0`, `17`, `latest`) and the image is
published multi-arch (amd64/arm64); the rolling `17.0` / `17` / `latest` tags
move with every stable publish, while a prerelease gets only its exact tag.
`@objectstack/cli` versions: a stable publish pushes that exact version as
`X.Y.Z` and moves `latest` and the matching `X.Y` / `X` tags onto it, while a
prerelease gets only its exact tag. The image is published multi-arch
(amd64/arm64). Only the exact tag is immutable — a rolling tag stops moving as
soon as no later publish matches it, so `X.Y` freezes when the next minor ships
and `X` when the next major does.
**Pin the exact version in production**, matching the CLI version in your
`package.json`.

Expand Down
6 changes: 3 additions & 3 deletions content/docs/upgrading.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -8,7 +8,7 @@ There are **two upgrades** on this platform, and they run on separate clocks:
| | Platform runtime | Metadata app |
| :--- | :--- | :--- |
| Ships as | a Docker image (or the `os` CLI on a host) | a compiled artifact, `dist/objectstack.json` |
| Versioned by | our release train (`17.0.0`) | your own catalog |
| Versioned by | our release train (`X.Y.Z`) | your own catalog |
| Whose cadence | ours | yours |
| The upgrade action | move the image tag, restart | `os migrate meta --from 16`, then rebuild and ship |
| Touches your metadata? | no | yes — you edit your source, guided by the tool's change list |
Expand All@@ -33,8 +33,8 @@ package shares one version number, and that number is the platform version.
### Moving the tag

The official image is `ghcr.io/objectstack-ai/objectstack`, and its tags mirror
`@objectstack/cli` versions (`17.0.0`, `17.0`, `17`, `latest`). **Pin the exact
version in production** and move it deliberately:
`@objectstack/cli` versions: the exact `X.Y.Z`, plus the rolling `X.Y`, `X` and
`latest` tags. **Pin the exact version in production** and move it deliberately:

```bash
# docker-compose.yml, or your orchestrator's manifest
Expand Down
Loading
Loading