Docker

Run the licensed ObjectOS runtime image with Docker — digest-pinned, signature-verified, licensed, and scaled to multiple replicas.

Docker is the supported way to run ObjectOS Self-Managed. Your release ships a deploy bundle containing a Compose stack, an environment template per deployment shape, and a README with the commands for your exact version. This page is the decision map for what that bundle configures.

What you are given

Your licence comes with registry credentials for the private runtime image. Signing in requires a token with package read access; there is no public image and no source build: the image is produced by our release pipeline from sources that are not distributed, so docker build is not a path that exists for you.

Supported architecture: linux/amd64 only. That is a declaration, not an omission: the build refuses to produce an image for an architecture we have not declared. Apple Silicon and Graviton hosts would run it under emulation, which is fine for a look and wrong for production.

Pin the image by digest

The image reference you run in production is a digest, not a tag:

OS_EE_IMAGE=<the registry reference from your release>@sha256:<64 hex characters>

A tag is a human-readable name and can be re-pointed at different bytes. A digest is content-addressed: the same digest is always the same image, on every host, forever. With a tag, a routine docker compose pull can replace the version you are running with no deployment event — and afterwards there is no way to prove what was actually running when something went wrong. Your release notes give the digest; paste it verbatim.

Keep the previous digest too. That is what a rollback is.

The image can tell you what it is

Two different version numbers travel with the image and should not be conflated: the product version of ObjectOS, and the compatibility range of the ObjectStack runtime embedded in it, which moves on its own schedule. Both — along with the source revisions the image was built from — are recorded inside the image itself, as OCI labels and as a machine-readable release manifest. You never have to ask us which build you have.

That manifest is also the single most useful thing to attach to a support request: it is enough to reproduce your exact image.

Verify the image before production

The image is signed (keyless, through our release pipeline's OIDC identity) and ships with an SBOM and build provenance. Verify once, before a production rollout — the three checks answer three different questions:

Check	The question it answers
Signature	Was this digest produced by the ObjectOS release pipeline, and not by someone else?
SBOM	What is inside this image?
Provenance	How was this image built, from which sources?

The bundle README carries the verification commands with the identity and issuer to check against, matched to your release.

Licence

A licence is part of the happy path. How the runtime behaves without one depends on what you asked it to be:

Single-organization, no licence — the deployment runs with Community behaviour: the open MCP server, bring your own AI. Nothing bricks.
Single-organization, licensed — the in-product AI is unlocked on your own infrastructure: the AI Builder and "ask your data".
Multi-organization (a walled tenancy posture), no licence — the runtime exits at startup, naming the licence. Isolation between organizations is a licensed capability, and a deployment that asked for isolation must never serve traffic pretending to have it.

There is a second constraint on the same line, and it is the one that surprises people: a licence has a mode, and the mode is coupled to your cloud posture. An ordinary licence is validated online against a control plane; an air-gap licence is verified locally and needs no network at all. Pairing an ordinary licence with "no control plane" is not a degraded state, it is an impossible one — and it is refused at startup, naming both settings, rather than failing later with a misleading complaint about the licence. Air-gapped has the full matrix of supported combinations.

A walled deployment must declare two more decisions

On a multi-organization posture, two settings have no safe default, so the runtime refuses to start until you decide them — declaring either available value is accepted; not deciding is not:

Decision	Why it cannot default
What a new sign-up joins	Where a membership is the tenant boundary, it may only be granted by an explicit act — an invitation, an admin, SSO provisioning. Automatic joining would put a stranger inside an existing organization.
Which AI agents are mounted	The "ask" agent reads; the "build" agent authors metadata — and metadata is scoped to the deployment, not to an organization. On a shared database, one customer's build turn rewrites the schema every other customer runs on.

A single-organization deployment sees neither check.

The shipped stack

The Compose stack in the bundle sequences a deployment the way it has to be sequenced, and it is worth knowing the order because any other orchestrator has to reproduce it:

The database becomes healthy.
A one-shot migration runs the schema to completion — before any application replica starts, so concurrent replicas never run schema changes against each other.
Application replicas start. The image carries its own health check.
The reverse proxy begins forwarding only once a replica is genuinely answering — not merely spawned.

Two HTTP endpoints exist for this, and they are not interchangeable: /api/v1/health for liveness and /api/v1/ready for readiness. Readiness is backed by the data layer: since ObjectStack 17.0 /api/v1/ready answers 503 when a data driver stops answering, so a replica whose database has gone away is pulled from rotation rather than left serving errors. A datasource that objects bind to must also connect at startup or the boot fails outright — an unreachable database is a failed deploy, not a container that comes up and then errors on every request.

In production, point the deployment at your managed PostgreSQL (and Redis, if you cluster) and remove the bundled database services. Give the proxy your domain to get automatic HTTPS. The runtime container runs as a non-root user and keeps its runtime state on a declared volume.

Multi-node

Scaling past one replica changes what is mandatory:

Turn on the cluster driver (backed by Redis), and
A shared secret key becomes required. With no cluster driver the runtime mints and persists its own key. Across replicas those keys would silently diverge — so instead of diverging, the runtime refuses to start. Generate one key and give every replica the same value.
The auth secret must also be identical on every replica. Changing it invalidates every existing session and orphans the signing key; the environment template documents the one-time cleanup that goes with a rotation.

Multi-node and high availability are Enterprise capabilities — see License & Pricing.

Upgrade and rollback

Take the new digest from the release notes and read the image's release manifest before rolling it out: confirm the product major line is the one you are on, and check whether the embedded runtime's compatibility range moved. A runtime major-version move means breaking changes underneath — read that release's notes first.
Back up the database. Schema migrations are forward: rolling the image back does not roll the schema back.
Change the image digest and restart the stack. The migration runs to completion before new replicas take traffic.
Confirm readiness returns 200 and the replicas report healthy.
To roll back, restore the previous digest and repeat step 3 — valid as long as the version you are leaving made no incompatible schema change (the release notes say when it did).

Kubernetes — the same properties, on an orchestrator.
Air-gapped — the licence mode for disconnected sites.
Production Readiness — pre-flight checklist.
Observability — logs, metrics, audit.