OpsCommand on a customer's own infrastructure (PLAN 7.8, concept note 10 and 16 "Private Enterprise"): the same software as the hosted service, run by the customer, with its own identity provider, database and backup storage. Nothing is ever sent to OpsCommand: the licence is checked offline, updates arrive as images or as signed media.
Two packages, each installed from the package alone:
| Where | For | |
|---|---|---|
| Docker Compose | deploy/private/compose/ | one server; the bundled database and HTTPS proxy optional |
| Helm chart | deploy/private/helm/opscommand/ | Kubernetes; your own PostgreSQL recommended, the bundled one optional |
Both are tested on every change (CI job Private deployment): the Compose package is installed on a clean machine and the chart on a clean Kubernetes (kind) cluster, then every service is checked — migrations (and an upgrade that finds nothing to do), the API in private mode, the web app with its settings, the worker, an encrypted backup written, and database logins that cannot bypass row-level security.
What runs
| Service | Image | What it does |
|---|---|---|
| migrate | opscommand-migrate | Applies the migrations a database lacks (never a changed one) and makes the two database logins; runs before the others start, at every install and upgrade. |
| api | opscommand-api | The API, in private mode (DEPLOYMENT_MODE=private). |
| web | opscommand-web | The web app; its API address and sign-in mode are read when it starts (OPSCOMMAND_API_URL, OPSCOMMAND_AUTH_MODE=installation), so one image serves any installation. |
| worker | opscommand-worker | E-mail, pages, retention and scheduled work. |
| backup | opscommand-backup | A daily encrypted dump of the database, to the backup volume. |
| db | postgres:17 | Optional: the bundled database. |
All images run as unprivileged users. Release images are signed (Sigstore) with provenance and an SBOM (U-26).
Before installing
- A PostgreSQL 16 or 17 (or the bundled one), with a database and an owner role that has
BYPASSRLS: the migrations run as it. The API and the worker each get their own login, made by the migrations, which can never bypass row-level security. - Two addresses with TLS: one for the web app, one for the API (
PUBLIC_APP_URL,PUBLIC_API_URL). - Your identity provider (OpenID Connect: Microsoft Entra ID, Okta, Keycloak, Google …). Register OpsCommand as a web application (a confidential client) with the redirect address
<PUBLIC_API_URL>/v1/sso/installation/callbackand the scopesopenid email profile. Everyone signs in through it; signing in grants no membership — people join organisations by invitation or by SCIM (7.3). - Keys made once, kept as secrets:
SEAL_KEYS:echo "v1:$(openssl rand -base64 32)"— seals integration secrets.SSO_SIGNING_KEY:openssl ecparam -name prime256v1 -genkey -noout | openssl pkcs8 -topk8 -nocrypt | base64 -w0— signs OpsCommand's sessions.- database passwords:
openssl rand -hex 32each (letters and digits only: they go into connection addresses). - E-mail: your SMTP server, with TLS (
smtps://…:465, or port 587 with STARTTLS). - Backups: a certificate whose private key you keep elsewhere —
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-384 -nodes -days 3650 -subj "/CN=OpsCommand backups" -keyout backup.key -out backup.crt. Onlybackup.crtgoes to the server. How long backups are kept (BACKUP_KEEP_DAYS) is your policy and has no default. - The licence, from OpsCommand (below). Without it the installation runs read-only.
Installing with Docker Compose
cd deploy/private/compose # or the compose folder of the update media
cp .env.example .env # fill in every value; .env.example explains each one
cp /path/to/backup.crt config/backup.crt
docker compose --profile bundled-db --profile proxy up -d
Leave out --profile bundled-db to use your own PostgreSQL (DB_HOST, DB_ADMIN_USER, DB_ADMIN_PASSWORD), and --profile proxy when your own ingress terminates TLS; then the web app and the API listen on WEB_PORT and API_PORT (localhost by default). The bundled proxy (Caddy) gets certificates for APP_HOST and API_HOST from Let's Encrypt, or uses your own (see Caddyfile). Backups go to the volume backups, or to a path on your own storage (BACKUP_DIR; owned by user 999).
Installing with Helm
Create one Secret with every secret value, then install:
kubectl create namespace opscommand
kubectl -n opscommand create secret generic opscommand \
--from-literal=DB_ADMIN_PASSWORD=… --from-literal=API_DB_PASSWORD=… --from-literal=WORKER_DB_PASSWORD=… \
--from-literal=SEAL_KEYS=… --from-literal=SSO_SIGNING_KEY=… --from-literal=SMTP_URL=… \
--from-literal=INSTALLATION_OIDC_CLIENT_SECRET=… --from-literal=LICENCE=…
helm install opscommand deploy/private/helm/opscommand -n opscommand -f my-values.yaml
values.yaml lists every setting; the required ones are refused by name when missing (image.tag, publicAppUrl, publicApiUrl, oidc.issuer, oidc.clientId, email.from, database.host or database.bundled.enabled, and with backups on, backup.keepDays and backup.certificate). A migration Job runs at every install and upgrade (<release>-migrate-<revision>); the API, the worker and the backup wait for it. Pods run as non-root with no privileges; ingress.* publishes the two addresses.
The first administrator
Set PLATFORM_BOOTSTRAP_CODE_SHA256 to the SHA-256 of a one-time code (printf %s "<code>" | sha256sum), sign in, and claim platform ownership with the code (Platform → Setup); then remove the setting. Claiming is a change, so it needs the licence installed first. Platform staff create the first organisation and invite its administrator.
The licence
OpsCommand issues a licence for each installation: a line beginning OPSCOMMAND-LICENCE-1., set as LICENCE. It is signed with OpsCommand's licence key and checked at every request against the public keys built into the release; it is never checked online. Its terms are in the licence itself: who holds it, the installation it is for, its last day, the days of grace after that, and how many organisations it allows.
- Valid, or within its grace: everything works.
- Missing, false, or past its grace: read-only, never locked. Everyone can still sign in, read and export their records (Administration → Data, 7.7); nothing new is written, and every page says why.
GET <PUBLIC_API_URL>/v1/licenceshows the state.
For OpsCommand (the owner): node scripts/licence.mjs keygen <key id> makes a key pair offline — keep the private key, add the printed public key to apps/api/src/licence-keys.ts (a release carries the keys it accepts); node scripts/licence.mjs sign <key id> <private.pem> <terms.json> issues a licence. Until a key is added, no licence verifies and every private installation is read-only.
Updates
Updates are never automatic. Back up first, then:
- From a registry: Compose — set
OPSCOMMAND_VERSIONand rundocker compose up -d; Helm —helm upgrade opscommand deploy/private/helm/opscommand -n opscommand --reuse-values --set image.tag=<version>. The migrations run first and refuse a migration changed after it was applied. - Without a registry (update media): each release has
opscommand-<version>.tar(release workflow): every image, the Compose package and the chart, a SHA-256 manifest and its Ed25519 signature. Verify before loading anything —node verify-media.mjs . <OpsCommand's media public key>— thendocker load -i images.tar.gz, push the images to your own registry if your cluster pulls from one, and update as above. The verifier refuses a wrong key, a changed file, a missing file and an extra one. OpsCommand publishes its media public key; compare it through a channel you trust.
For OpsCommand: the media is signed when the repository secret MEDIA_SIGNING_KEY holds the media private key (made like the licence key); until then the media carries its manifest but no signature, and the verifier says so.
Backups and restore
Daily at BACKUP_HOUR (UTC) the backup service writes opscommand-<time>.dump.cms, encrypted to backup.crt, and its SHA-256. Copy them off the server as your policy requires. To restore, run the backup image with the backups, BACKUP_KEY and BACKUP_CERT mounted and TARGET_DATABASE_URL pointing at an empty database: /opt/opscommand/restore.sh latest (the same procedure as the hosted service, DEPLOY.md).
Limits of this version
- The web app's custom status-page domains (
APP_HOSTrewriting, PLAN 3.12) are fixed when the web image is built. - Single sign-on through the installation's provider only; OpsCommand's hosted identity project is not used.
- Billing (Stripe) is off: the licence takes its place.