@fabrika/provider-zerops 0.4.1 → 0.4.3

package/src/installation/deploy.ts

@@ -35,10 +35,14 @@
 // readiness gate.
 
 import { FABRIKA_SERVICE_TABLE_DIGEST, readEnvironmentName } from '@fabrika/auth-core'
+import { IAM_APP_ID, IAM_APP_SCHEMA } from '@fabrika/iam-contract'
 import type { SchemaReconciler } from '@fabrika/provider-contract'
 import { encodeProxyManifestJson, FABRIKA_PROXY_MANIFEST_JSON } from '@fabrika/proxy-core/manifest'
+import { assertServiceEnvValueFits } from '../api'
 import {
+	enableSubdomainAccessWhenHttp,
 	prepareZeropsDescriptor,
+	readableContent,
 	type Sleeper,
 	ZEROPS_ACTIVE,
 	ZEROPS_SERVICE_NOT_HTTP,
@@ -47,7 +51,10 @@ import {
 	ZeropsApiError,
 	type ZeropsNamespaceProxySource,
 	type ZeropsService,
+	type ZeropsServiceEnv,
 } from '../index'
+import { ZEROPS_PROXY_MANIFEST_PATH } from '../proxy-manifest-carrier'
+import { assertCheckerPublished, type CheckerPublication } from './checker-release'
 import type { PlatformDeployInput } from './deploy-options'
 import { PLATFORM_CONSOLE_APP_SCHEMA } from './generated/platform-console-schema'
 import { PLATFORM_PROXY_MANIFEST_TEMPLATE } from './generated/platform-proxy-manifest'
@@ -63,6 +70,7 @@ import {
 import type { DeployLog } from './log'
 import { mergePlatformProxyManifest, readLiveProxyManifest } from './manifest'
 import { type IamOAuthConfig, platformIamOAuthConfig } from './mcp'
+import { archiveWithDataFile } from './platform-archive'
 import type { PreparedPlatformSource } from './platform-source'
 import { type PlatformUploadFetch, uploadPlatformArchive } from './platform-upload'
 import { platformProxyAppFor, type PlatformProxyComposition, platformServiceTableDigest, resolvePlatformProxyManifest } from './proxy-manifest'
@@ -139,6 +147,7 @@ export interface PlatformServiceDeployCollaborators {
 /** Everything `deployPlatform` reaches the outside world through. */
 export interface PlatformDeployCollaborators extends PlatformServiceDeployCollaborators {
 	readonly prepareSource: PlatformSourcePreparer
+	readonly checkerPublished: CheckerPublication
 	readonly reconcileSchema: SchemaReconciler
 }
 
@@ -146,6 +155,16 @@ export interface PlatformDeployCollaborators extends PlatformServiceDeployCollab
 export interface PlatformServiceDeployInput {
 	readonly source: PreparedPlatformSource
 	readonly dryRun: boolean
+	/** The proxy's manifest, which its archive carries as the one data file (ADR-0045); the proxy is refused without it. */
+	readonly proxyManifest?: string
+}
+
+/** The archive one service builds from: the snapshot, and for the proxy the snapshot plus its manifest. */
+const serviceArchive = async (service: ResolvedService, input: PlatformServiceDeployInput): Promise<Blob> => {
+	const snapshot = Bun.file(input.source.archivePath)
+	if (service.hostname !== PLATFORM_PROXY_SERVICE) return snapshot
+	if (input.proxyManifest === undefined) throw new Error('the proxy is built only with the manifest its archive carries')
+	return new Blob([archiveWithDataFile(await snapshot.bytes(), { path: ZEROPS_PROXY_MANIFEST_PATH, contents: input.proxyManifest })])
 }
 
 /** One resolved platform service. */
@@ -237,13 +256,16 @@ export const serviceOf = (services: ReadonlyMap<PlatformDeployService, ResolvedS
 	return service
 }
 
-/** Read one service's environment as a key → value map. Values are never logged. */
+/** One service's environment by key. A sensitive record carries no value. Values are never logged. */
+export type LiveServiceEnv = ReadonlyMap<string, ZeropsServiceEnv>
+
+/** Read one service's environment by key. */
 export const readServiceEnv = async (
 	serviceId: string,
 	{ api, signal }: Pick<PlatformServiceDeployCollaborators, 'api' | 'signal'>,
-): Promise<Map<string, string>> => {
+): Promise<LiveServiceEnv> => {
 	const variables = await api.listServiceEnv({ serviceId, signal })
-	return new Map(variables.map((variable) => [variable.key, variable.content]))
+	return new Map(variables.map((variable) => [variable.key, variable]))
 }
 
 /**
@@ -254,11 +276,11 @@ export const readServiceEnv = async (
  * `custom-domain` installation, where the domains are bound to the project balancer out of band and
  * publishing a subdomain would add a public address nobody asked for.
  */
-const resolvePlacement = (input: PlatformDeployInput, proxyEnv: ReadonlyMap<string, string>): PlatformPlacement => {
+const resolvePlacement = (input: PlatformDeployInput, proxyEnv: LiveServiceEnv): PlatformPlacement => {
 	if (input.hosts !== undefined) {
 		return { hosts: input.hosts, scheme: input.scheme, zeropsSubdomain: false }
 	}
-	const subdomains = proxyEnv.get(ZEROPS_SUBDOMAIN_VARIABLE)
+	const subdomains = readableContent(proxyEnv.get(ZEROPS_SUBDOMAIN_VARIABLE))
 	if (subdomains === undefined || subdomains.trim() === '') {
 		throw new Error(
 			'the proxy service publishes no Zerops subdomain — deploy it once so it has HTTP ports, or name every host '
@@ -281,7 +303,6 @@ const IAM_OAUTH_CONFIG = 'FABRIKA_IAM_OAUTH_CONFIG'
 const desiredServiceEnv = (
 	environment: string,
 	placement: PlatformPlacement,
-	manifestJson: string,
 	proxySource: ZeropsNamespaceProxySource,
 	oauthConfig: IamOAuthConfig | undefined,
 	controlTableDigest: string,
@@ -314,7 +335,6 @@ const desiredServiceEnv = (
 				// Compared byte-for-byte against a token's `iss`, so this is the PUBLIC issuer and not the
 				// private `iam:3000` the manifest dials — `readProxyEnv` canonicalizes it to an origin.
 				['FABRIKA_IAM_ISSUER', iamOrigin],
-				[FABRIKA_PROXY_MANIFEST_JSON, manifestJson],
 				['FABRIKA_PROXY_SESSION_OWNER_JSON', JSON.stringify({ issuer: iamOrigin, upstream: PRIVATE_IAM_UPSTREAM })],
 			]),
 		],
@@ -338,25 +358,32 @@ const desiredServiceEnv = (
 	])
 }
 
-/** Write only what differs. Returns the KEYS written — never a value, not even in a debug line. */
+/**
+ * Write only what differs. Returns the KEYS written — never a value, not even in a debug line.
+ *
+ * Nothing here is a credential, so everything is written readable. A record an older release wrote
+ * sensitive reads as different and is rewritten readable, which is what lets the next deploy compare it.
+ */
 const applyServiceEnv = async (
 	service: ResolvedService,
 	desired: ReadonlyMap<string, string>,
-	live: ReadonlyMap<string, string>,
+	live: LiveServiceEnv,
 	input: PlatformDeployInput,
 	collaborators: PlatformDeployCollaborators,
 ): Promise<string[]> => {
 	const written: string[] = []
 	for (const [key, value] of desired) {
-		if (live.get(key) === value) {
+		if (readableContent(live.get(key)) === value) {
 			continue
 		}
 		written.push(key)
+		// The client refuses it too; checking here lets a dry run report what the real write would refuse.
+		assertServiceEnvValueFits(key, value)
 		if (input.dryRun) {
 			continue
 		}
 		assertRunning(collaborators.signal)
-		await collaborators.api.putServiceEnv({ serviceId: service.id, key, value, signal: collaborators.signal })
+		await collaborators.api.putServiceEnv({ serviceId: service.id, key, value, sensitive: false, signal: collaborators.signal })
 	}
 	return written
 }
@@ -434,11 +461,12 @@ export const deployPlatformService = async (
 		return
 	}
 	prepareZeropsDescriptor(input.source.descriptor.contents, service.hostname)
+	const archive = await serviceArchive(service, input)
 	const reserved = await api.createAppVersion({ serviceId: service.id, name: input.source.commitSha, signal })
 	const appVersionId = reserved.id
 	log.info(`${service.hostname}: app-version ${appVersionId}, commit ${input.source.commitSha}, setup ${service.hostname}`)
 	try {
-		await uploadPlatformArchive(reserved.uploadUrl, input.source.archivePath, signal, collaborators.uploadFetch)
+		await uploadPlatformArchive(reserved.uploadUrl, archive, signal, collaborators.uploadFetch)
 		assertRunning(signal)
 	} catch {
 		await cleanupReservation(service, appVersionId, collaborators)
@@ -502,7 +530,8 @@ const deployConcurrently = async (
  * The decision is the READ-BACK and never the call returning: on an already-published service the
  * platform answers 2xx and then fails the process it hands back, and a freshly-enabled one can still
  * read `false` on the next read. Both live-verified. Runs on every deploy, so a subdomain someone
- * turned off in the GUI comes back, and throws rather than leaving the installation unreachable.
+ * turned off in the GUI comes back, and throws rather than leaving the installation unreachable. The
+ * HTTP ports lag a fresh ACTIVE version, so `serviceStackIsNotHttp` is retried for a bounded window first.
  */
 const ensureSubdomainAccess = async (
 	proxy: ResolvedService,
@@ -519,11 +548,11 @@ const ensureSubdomainAccess = async (
 		return
 	}
 	try {
-		await api.enableSubdomainAccess({ serviceId: proxy.id, signal })
+		await enableSubdomainAccessWhenHttp({ api, serviceId: proxy.id, sleep, signal })
 	} catch (error) {
 		if (error instanceof ZeropsApiError && error.code === ZEROPS_SERVICE_NOT_HTTP) {
 			throw new Error(
-				`the proxy cannot be published on a zerops.app subdomain: it exposes no deployed HTTP port (${ZEROPS_SERVICE_NOT_HTTP})`,
+				`the proxy cannot be published on a zerops.app subdomain: it still exposes no deployed HTTP port (${ZEROPS_SERVICE_NOT_HTTP}) minutes after its deploy`,
 			)
 		}
 		throw error
@@ -569,6 +598,7 @@ export const deployPlatform = async (
 	const source = await collaborators.prepareSource(input.sourceDir, collaborators.signal)
 	try {
 		validateInstallationSetups(source, PLATFORM_DEPLOY_ORDER)
+		await assertCheckerPublished(collaborators.checkerPublished, collaborators.signal)
 		await deployPreparedPlatform(input, collaborators, source)
 	} finally {
 		await source.dispose()
@@ -617,6 +647,7 @@ export const deployPreparedPlatform = async (
 			? 'MCP authoring: off'
 			: `MCP authoring: on, ${oauthConfig.clients.length} client(s), resource(s) ${oauthConfig.resources.map((entry) => entry.resource).join(', ')}`,
 	)
+	// The variable is the application entries the platform proxy carries, held by the operator; nothing here writes it.
 	const merged = mergePlatformProxyManifest(platformManifest, readLiveProxyManifest(proxyEnv.get(FABRIKA_PROXY_MANIFEST_JSON)))
 	log.info(`${merged.manifest.apps.length} app(s): ${merged.manifest.apps.map((app) => app.id).join(', ')}`)
 	if (merged.carried.length > 0) {
@@ -631,12 +662,14 @@ export const deployPreparedPlatform = async (
 
 	log.step('Write the service environment')
 	const controlTableDigest = platformServiceTableDigest(platformManifest, platformProxyAppFor(PLATFORM_PROXY_MANIFEST_TEMPLATE, 'control').id)
-	const desired = desiredServiceEnv(environment, placement, encodeProxyManifestJson(merged.manifest), proxySource, oauthConfig, controlTableDigest)
+	const desired = desiredServiceEnv(environment, placement, proxySource, oauthConfig, controlTableDigest)
 	for (const hostname of PLATFORM_DEPLOY_ORDER) {
 		const service = serviceOf(services, hostname)
 		const live = hostname === PLATFORM_PROXY_SERVICE ? proxyEnv : await readServiceEnv(service.id, collaborators)
 		const keys = desired.get(hostname) ?? new Map<string, string>()
-		if (hostname === 'iam' && oauthConfig === undefined && (live.get(IAM_OAUTH_CONFIG) ?? '').trim() !== '') {
+		const liveOAuthConfig = live.get(IAM_OAUTH_CONFIG)
+		const oauthStillSet = liveOAuthConfig !== undefined && (liveOAuthConfig.sensitive || liveOAuthConfig.content.trim() !== '')
+		if (hostname === 'iam' && oauthConfig === undefined && oauthStillSet) {
 			log.warn(`iam: MCP authoring is off but ${IAM_OAUTH_CONFIG} is still set; IAM keeps issuing MCP tokens until it is removed`)
 		}
 		const written = await applyServiceEnv(service, keys, live, input, collaborators)
@@ -647,11 +680,12 @@ export const deployPreparedPlatform = async (
 		)
 	}
 
-	// EVERY deploy is after EVERY write. That is what makes the sequence fail closed: a manifest this
-	// command could not apply leaves the previous manifest in front of the previous code, never in front
-	// of new code — and `ENVIRONMENT` is in place before any service that refuses `local` restarts.
+	// EVERY deploy is after EVERY write, and the manifest rides in the proxy's own archive. That is what makes
+	// the sequence fail closed: a proxy build that does not go ACTIVE leaves the previous manifest in front of
+	// the previous code, because control builds only after it — and `ENVIRONMENT` is in place before any
+	// service that refuses `local` restarts.
 	log.step(`Deploy ${PLATFORM_CONCURRENT_DEPLOY.join(' + ')} together, then ${PLATFORM_SEQUENTIAL_DEPLOY.join(' → ')}`)
-	const buildInput = { source, dryRun: input.dryRun }
+	const buildInput = { source, dryRun: input.dryRun, proxyManifest: encodeProxyManifestJson(merged.manifest) }
 	await deployConcurrently(services, buildInput, collaborators)
 	for (const hostname of PLATFORM_SEQUENTIAL_DEPLOY) {
 		await deployPlatformService(serviceOf(services, hostname), buildInput, collaborators)
@@ -669,11 +703,12 @@ export const deployPreparedPlatform = async (
 		log.info('custom-domain installation: the operator binds each domain to the project balancer; no subdomain is published')
 	}
 
-	log.step('Register the console with IAM')
+	log.step('Register the console and IAM with IAM')
 	const consoleApp = platformProxyAppFor(PLATFORM_PROXY_MANIFEST_TEMPLATE, 'control')
 	const consoleOrigin = platformOrigin(placement.scheme, placement.hosts.control)
 	if (input.dryRun) {
 		log.info(`would reconcile \`${consoleApp.id}\` and register its return origin ${consoleOrigin}`)
+		log.info(`would reconcile \`${IAM_APP_ID}\`'s own vocabulary`)
 	} else {
 		// The schema PUT is what REGISTERS the app, and `apps.setReturnOrigins` 404s for an app IAM has
 		// never heard of — so both travel in this one call, in that order (ADR-0022/ADR-0023).
@@ -686,6 +721,15 @@ export const deployPreparedPlatform = async (
 			signal,
 		})
 		log.info(`\`${consoleApp.id}\` reconciled; return origin ${consoleOrigin}`)
+		// IAM's own vocabulary, which `user-admin` is granted from (ADR-0058). It has no return origin.
+		await collaborators.reconcileSchema({
+			url: platformOrigin(placement.scheme, placement.hosts.iam),
+			app: IAM_APP_ID,
+			schema: IAM_APP_SCHEMA,
+			adminKey: input.iamAdminKey,
+			signal,
+		})
+		log.info(`\`${IAM_APP_ID}\` reconciled`)
 	}
 
 	log.step(input.dryRun ? 'Dry run complete — nothing was written' : 'Installation deployed')

package/src/installation/generated/platform-console-schema.ts

@@ -11,6 +11,7 @@
 import type { AppSchema } from '@fabrika/auth-core'
 
 export const PLATFORM_CONSOLE_APP_SCHEMA: AppSchema = {
+	displayName: 'Console',
 	scopes: [
 		{ type: 'app', label: 'App' },
 		{ type: 'environment', label: 'Environment' },
@@ -31,14 +32,29 @@ export const PLATFORM_CONSOLE_APP_SCHEMA: AppSchema = {
 		{ action: 'operations.manage', description: 'Manage Operations sources, alerts, and retention' },
 	],
 	roles: {
+		observer: {
+			name: 'Observer',
+			description: 'Read Operations errors and activity.',
+			permissions: ['operations.read'],
+		},
+		triager: {
+			name: 'Triager',
+			description: 'Read and triage Operations errors.',
+			permissions: ['operations.read', 'operations.triage'],
+		},
+		deployer: {
+			name: 'Deployer',
+			description: 'Trigger, read and cancel deploys (no registry, namespace or secret management).',
+			permissions: ['deploy.*'],
+		},
 		operator: {
 			name: 'Operator',
-			description: 'Trigger and read any deploy (no registry or secret management).',
+			description: 'Deploy, and read, triage and manage Operations (no registry or secret management).',
 			permissions: ['deploy.*', 'operations.*'],
 		},
 		admin: {
 			name: 'Admin',
-			description: 'Full access to every vozka action in every scope.',
+			description: 'Every console action in every scope.',
 			permissions: ['*'],
 		},
 	},

package/src/installation/generated/platform-proxy-manifest.ts

@@ -278,6 +278,16 @@ export const PLATFORM_PROXY_MANIFEST_TEMPLATE: PlatformProxyManifestTemplate = {
 						admission: null,
 						oauth: null,
 					},
+					{
+						id: 'github-setup',
+						kind: 'service',
+						method: 'GET',
+						path: '/api/source/github/setup/:connectionId',
+						callers: ['human'],
+						requirement: { kind: 'authenticated' },
+						admission: null,
+						oauth: null,
+					},
 					{
 						id: 'rpc',
 						kind: 'service',
@@ -453,6 +463,16 @@ export const PLATFORM_PROXY_MANIFEST_TEMPLATE: PlatformProxyManifestTemplate = {
 						admission: null,
 						oauth: null,
 					},
+					{
+						id: 'github-setup',
+						kind: 'service',
+						method: 'GET',
+						path: '/api/source/github/setup/:connectionId',
+						callers: ['human'],
+						requirement: { kind: 'authenticated' },
+						admission: null,
+						oauth: null,
+					},
 					{
 						id: 'rpc',
 						kind: 'service',

package/src/installation/guide.md

@@ -0,0 +1,319 @@
+# Installing fabrika on Zerops — the operator's guide
+
+From an empty Zerops account to a serving application. This guide ships with the CLI, so it matches the
+release you run. It gives the order and the traps. Each command's flags are in its own help, and that text
+is authoritative:
+
+```bash
+fabrika platform --provider=zerops --help
+fabrika control --help
+```
+
+Run the steps in order and check each one before the next. Every command refuses a missing value with a
+message that names the flag or the variable to set. Read the message: it names the fix.
+
+## Before you start
+
+**Ask the human for these first.** You cannot produce them, and each one blocks a later step:
+
+| What                                                                                  | Needed at  |
+| ------------------------------------------------------------------------------------- | ---------- |
+| A Zerops PERSONAL access token of a client OWNER, generated in the Zerops GUI         | step 1     |
+| A verified Zerops account (credit topped up once); an unverified one owns ONE project | step 5     |
+| A `gh` login allowed to create a repository in the organization that owns it          | step 3     |
+| The administrator's e-mail address, and the human to open the enrollment URL          | step 2     |
+| For a PRIVATE application repository: the GitHub App connected in the console         | step 5     |
+| The fabrika release tag to install, for example `v0.4.3` (a branch is refused)        | steps 1, 3 |
+| The four decisions below                                                              | steps 1, 5 |
+
+Every namespace is a Zerops project of its own, so the first one fails with `clientProjectCountLimitExceededTopUp`
+on an unverified account (observed 2026-10-15).
+
+Also needed on the machine: [Bun](https://bun.sh) ≥ 1.3, `git`, `gh`, `curl` and `jq`.
+
+## Decisions: ask the human, with the prices
+
+Each choice trades price against stability, and two of them cannot be undone. Show the human this section
+and let them choose; do not pick for them. Prices are Zerops' list prices as of 2026-10-15
+([zerops.io/pricing](https://zerops.io/pricing)): a shared core $0.60, a dedicated core $6.00, RAM $3.00 per
+GB, disk $0.10 per GB and object storage $0.01 per GB, each per 30 days and billed per minute. A Lightweight
+project core is free (15 build hours, 100 GB egress); a Serious one is $10 (150 build hours, 3 TB egress, a
+highly available balancer). The figures below are the idle FLOOR. Every service scales up under load, to 8
+cores and 48 GB per container, and costs more while it does.
+
+**1. Platform tier** (`platform install --tier`, step 1). Cannot be changed later: a project's core package
+is upgrade-only, and the data services differ.
+
+| Tier              | What runs                                                                                                                                                                           | Idle floor | Fails when                                               |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------------------------------------------------------- |
+| `light` (default) | Lightweight core. One single-node PostgreSQL (`oltp-hobby`) and one bucket shared by IAM, control and Operations; one container each.                                               | about $6   | any one container or the database is down: sign-in stops |
+| `standard`        | Serious core. HA PostgreSQL (3 nodes, `oltp-production`, dedicated CPU) for IAM and control; a second HA PostgreSQL and bucket for Operations; two containers of IAM and the proxy. | about $100 | survives the loss of one node of each                    |
+
+Most of `standard`'s price is the identity database's dedicated floor (about $72). `light` is right for an
+evaluation and a small fleet that tolerates an outage; `standard` for sign-in that must stay up.
+
+**2. Namespace preset** (`control namespaces create --preset`, step 5). A namespace is the Zerops project
+applications run in. Each one adds its own proxy, about $1.08.
+
+| Preset          | Where an application's database lives                                   | Use with                             |
+| --------------- | ----------------------------------------------------------------------- | ------------------------------------ |
+| `cheap`         | One shared single-node PostgreSQL in the namespace, about $1.45 for all | `fabrika.cheap.config.ts`            |
+| `mid` (default) | Each application imports its own database into the namespace            | `fabrika.config.ts`                  |
+| `full`          | The namespace belongs to ONE application (`--exclusive-app=<id>`)       | an application that must be isolated |
+
+**3. The application's database** (the application's `fabrika.config.ts`, before step 5). The example
+declares `postgresql:single@18` at `oltp-hobby`, about $1.45, plus its runtime from about $1.08 per
+container. `postgresql:ha@18` survives a node failure: about $11 at `oltp-staging` (shared CPU), about $72 at
+`oltp-production` (dedicated). Single to HA later means a new service and a data migration.
+
+**4. Namespace core package** (`--core-package=LIGHT|SERIOUS`, step 5). `LIGHT` is free and the default on
+every environment. `SERIOUS` adds $10 per namespace and a highly available balancer in front of its proxy,
+and it can never be downgraded again.
+
+## Secrets: rules for an agent
+
+- Every credential is read from the ENVIRONMENT ONLY. No command takes one as a flag.
+- Never print a credential, never put one in a command line you echo, never commit one.
+- `platform install` writes every credential it creates to `--secrets-file`, mode `0600`, before it places
+  the first one. That file is the ONLY readable copy. Zerops stores them as sensitive variables and answers
+  `REDACTED` when they are read back, so never try to read a secret from the Zerops API, and never ask the
+  human for sudo mode to do it. Back the file up where the human keeps credentials.
+- Load the file in a subshell, so its integration token never replaces the personal one in your shell:
+  `( set -a && . <secrets file> && set +a && fabrika … )`.
+- Keep any other credential in its own `0600` file (`umask 077` first) and pass it as `NAME="$(cat <file>)"`.
+  Check a file with `wc -c`, never with `cat`.
+
+## Step 0. Get the CLI at the release tag
+
+`platform install` and `platform deploy` upload the source of the checkout the CLI runs from, and refuse
+anything else (`--source-dir`). So the bring-up runs from a clean clone at the tag, not from a CLI installed
+with `bun add --global`:
+
+```bash
+git clone --depth 1 --branch <tag> https://github.com/contember/fabrika-platform.git fabrika-platform
+cd fabrika-platform && bun install --frozen-lockfile
+```
+
+In this guide, `fabrika` means `bun <clone>/packages/cli/src/index.ts`. Do not edit the clone: a dirty
+checkout is refused, and a local commit is not on GitHub, so namespaces cannot fetch it.
+
+Install a released tag, not a branch. Every application build fetches `@fabrika/check` at the version of the
+checkout, so `install` and `deploy` refuse a checkout whose version npm does not have yet: `this checkout is
+version X, which is not published yet`. A `main` between a release's version bump and its publish is such a
+checkout.
+
+## Step 1. Install the platform
+
+```bash
+export FABRIKA_ZEROPS_ACCESS_TOKEN="$(cat <personal token file>)"
+curl -s -H "Authorization: Bearer $FABRIKA_ZEROPS_ACCESS_TOKEN" \
+  https://api.app-prg1.zerops.io/api/rest/public/user/info | jq '{email, clients: [.clientUserList[] | {clientId, name: .client.accountName, role: .roleCode}]}'
+fabrika platform install --provider=zerops --create-project --client-id=<clientId> --env=<name> --tier=<light|standard> \
+  --secrets-file=<path outside the clone> --source-dir=. --yes > install.log 2>&1
+```
+
+- Check the token kind first. The `email` of a personal token is the person's address, and its `role` on the
+  client is `OWNER`. An `email` of `token-<id>@zerops.io` is an INTEGRATION token. The install refuses one before
+  it creates anything, because an integration token may not mint the token the control plane needs. Ask the
+  human for a personal token instead.
+- Run it from the clone root. It runs for many minutes: it imports the tier's services, builds the proxy
+  once to learn the public hosts, then deploys everything.
+- `--yes` is required when stdin is not a terminal.
+- `--secrets-file` names a NEW file outside the clone, for example `~/fabrika-<env>.secrets.env`. An existing
+  file is refused. The log prints no credential.
+- The project id is printed BEFORE the long wait. If the run is interrupted, re-run with
+  `--project-id=<id>` instead of `--create-project`.
+- A project that already holds generated secrets is refused. Do not try to force it: a second bring-up
+  over the same project would destroy the vault key. Start over in a new empty project.
+- The account must be in the default region, or set `FABRIKA_ZEROPS_API_URL` for every command.
+
+**Check.** The log ends with the `Hand off` step: where the credentials are, `The console answers at
+https://<console host>`, and an `ADMIT YOURSELF` box that holds the step 2 command with `--iam-host` filled
+in. The secrets file exists with mode `0600`. The three hosts are printed earlier, right after pass 1, as
+`✓ iam <host>`, `✓ console <host>` and `✓ operations <host>`. Write them down.
+
+## Step 2. Admit the first administrator
+
+```bash
+( set -a && . <secrets file> && set +a && \
+  fabrika platform admin --provider=zerops --email=<address> --iam-host=<IAM host from step 1> )
+```
+
+It prints one enrollment URL and the time it expires. Nothing is e-mailed: the installation has no mail
+service, so do not tell the human to wait for a message. The URL is a credential: give it to the human only,
+and do not log it. The human opens it, sets a password and signs in at the console origin.
+
+The URL is valid for ONE HOUR. Hand it over at once. A re-run creates nothing new: while the enrollment is
+unused it only reports that one is outstanding, and it never prints the URL again. To get a new URL, after
+expiry or after a lost one, run the same command with `--reissue`. It replaces the old enrollment, so the old
+URL stops working.
+
+## Step 3. Create the sidecar repository
+
+The sidecar is a GitHub repository the operator owns. Its workflow runs `platform deploy` at the pinned tag.
+
+Steps 4 and 5 do not depend on this step: the installation from step 1 already runs. The sidecar is what
+upgrades it later (step 6). Run this step before or after step 5. Only `platform upgrade` needs it.
+
+`init` takes the integration token step 1 minted, never the personal one. The secrets file holds it as
+`FABRIKA_ZEROPS_ACCESS_TOKEN`, beside the provisioning key. Run `init` from a directory that is NOT inside
+any git repository. The fabrika clone is a repository, and a home directory under dotfiles version control is
+one too. Otherwise pass `--checkout=<dir>` outside one:
+
+```bash
+( set -a && . <secrets file> && set +a && \
+  fabrika platform init --provider=zerops <installation> --repo=<owner>/<name> --tag=<tag> \
+  --project-id=<project id> --env=<name from step 1> --yes < /dev/null )
+```
+
+- Without `--repo` the repository is `contember/fabrika-zerops-<installation>`. Pass `--repo` for any
+  other organization.
+- Keep the local checkout path. `platform upgrade` needs it later (`--sidecar=<dir>`).
+
+**Check.** The `platform` workflow run in the sidecar repository ends green:
+`gh run list --repo <owner>/<name>`.
+
+## Step 4. Mint a machine key for `fabrika control`
+
+```bash
+( umask 077 && set -a && . <secrets file> && set +a && FABRIKA_IAM_RPC_URL=https://<IAM host> \
+  fabrika control key issue --label=<name> --permissions=app.manage,namespace.manage,deploy.trigger,deploy.read \
+  --expires-in=2592000 > control.key )
+wc -c control.key && ls -l control.key
+```
+
+The secrets file supplies `FABRIKA_IAM_RPC_KEY` and `FABRIKA_IAM_PROVISIONING_KEY`.
+
+- stdout carries the key and nothing else; the credential id goes to stderr. Keep the redirect inside the
+  `umask 077` subshell: `control.key` is then created with mode `0600` (`-rw-------`). Outside it, the file
+  is readable by other users.
+- `FABRIKA_IAM_RPC_URL` is IAM's PUBLIC `https://` origin. The private `http://iam:3000` answers only inside
+  the Zerops project.
+- A key expires after at most 30 days. Mint a new one when it does.
+
+For every `fabrika control` command from here on:
+
+```bash
+export FABRIKA_CONTROL_URL=https://<console host>
+FABRIKA_CONTROL_KEY="$(cat control.key)" fabrika control apps list
+```
+
+**Check.** On a fresh installation `apps list` prints `no applications registered yet` (on stderr) and
+exits 0. An authentication error means the key or the console origin is wrong.
+
+## Step 5. Deploy the first application
+
+The example is [`contember/fabrika-example-zerops`](https://github.com/contember/fabrika-example-zerops).
+Its `fabrika.config.ts` places the app with its own database (`mid` preset), and `fabrika.cheap.config.ts`
+places it on the namespace's shared PostgreSQL (`cheap` preset). Use the config that matches the preset.
+
+**Repository access decides how you register** (step 5.2). Check it first:
+`curl -s -o /dev/null -w '%{http_code}\n' https://api.github.com/repos/<owner>/<name>`.
+
+- `200`: the repository is public. Register it with `--installation-id=none`. Control reads it without a token.
+- `404`: GitHub hides it from an anonymous caller, so it is private (or the name is wrong). `register` refuses
+  it with `--installation-id=none`. Ask the human to connect the GitHub App in the console first (Settings →
+  Source, a browser flow), then register without `--installation-id`.
+
+**Use the installation's release in the application.** The application's `@fabrika/*` packages, the CLI
+among them, must be the version of the tag you installed: for `v0.4.3`, `^0.4.3`. Another version can build
+a manifest this installation's control refuses or reads differently. From the fabrika clone of step 0, run
+`bun scripts/release.ts example-pin <application checkout> --tag=<tag>`. It rewrites every `@fabrika/*` range
+and commits nothing. Commit and push the change in the application repository, then run `bun install` there.
+Check with `bun pm ls | grep @fabrika/cli`.
+
+1. **Create a namespace** with the preset and core package the human chose (see Decisions). Without a
+   custom domain bound to its proxy, pass `--public-access=zerops-subdomain`; the default is
+   `custom-domain`, which serves no host until you bind one.
+
+   ```bash
+   fabrika control namespaces plan   --namespace=<id> --env=<name> --preset=<cheap|mid|full> --public-access=zerops-subdomain
+   fabrika control namespaces create --namespace=<id> --env=<name> --preset=<cheap|mid|full> --public-access=zerops-subdomain
+   fabrika control namespaces get    --namespace=<id>
+   ```
+
+   `create` returns while the state is `pending`. Provisioning takes several minutes. Poll `get` every
+   30 seconds until it is `ready`.
+
+   - If the state is `failed`, `get` prints the cause and the command that resumes it on stderr. Run
+     `fabrika control namespaces reconcile --namespace=<id>` and poll `get` again. Provisioning resumes from
+     where it stopped. Do not create a second namespace.
+   - `get` lists one host per line as `<host> <port> free` or `<host> <port> taken by <app>/<env>`. A
+     `zerops-subdomain` namespace has six hosts, one per public port of its proxy: 8080 and 8082–8086. No
+     port is special or reserved; 8081 is the proxy's health port and is never listed. Use ANY `free` host,
+     for example the first one. Each host serves exactly one application environment, so six is the limit
+     per namespace.
+
+2. **Build and register**, from the application's repository root. The repository must be pushed: control
+   deploys the commit on GitHub, not your working tree.
+
+   `--app=<id>` is the application id the manifest carries: `jq -r .app.id fabrika.manifest.json` after the
+   build. The application's `fabrika.config.ts` sets it (`defineApp({ id })`); the example takes it from its
+   contract's vocabulary, and it is `notes`.
+
+   ```bash
+   bun install
+   bunx fabrika app build --env=<name>                          # cheap: add --config=fabrika.cheap.config.ts
+   FABRIKA_CONTROL_KEY="$(cat control.key)" bunx fabrika control register --provider=zerops --app=<id> \
+     --repo=https://github.com/<owner>/<name> --env=<name> --manifest=fabrika.manifest.json \
+     --namespace=<namespace id> --domain=<free host> --installation-id=none
+   ```
+
+   - `--installation-id=none` works only for a repository GitHub serves without a token. `register` reads it
+     once and refuses one that is not publicly readable, so the failure shows here and not at deploy. A
+     private repository needs the GitHub App connected in the console first (Settings → Source, a browser
+     flow for the human); then omit the flag.
+   - `register` CREATES and refuses a second registration. A changed manifest goes through
+     `control apps environments put` with the same placement flags.
+
+3. **Deploy and follow it.**
+
+   ```bash
+   FABRIKA_CONTROL_KEY="$(cat control.key)" bunx fabrika control deploy --app=<id> --env=<name>
+   FABRIKA_CONTROL_KEY="$(cat control.key)" bunx fabrika control runs list --app=<id>
+   FABRIKA_CONTROL_KEY="$(cat control.key)" bunx fabrika control runs log --run=<run id>
+   ```
+
+   A failed run's log ends with `deploy failed: <reason>`. For example, `source resolve failed
+   (ref_not_found)` means control could not read the repository or the ref.
+
+   The deploy fails when the repository at the deployed commit does not match the registered manifest.
+   Commit and push, rebuild the manifest, `apps environments put` it, and deploy again.
+
+   On an environment named `prod`, a change that widens access waits for a person to approve it in the
+   console before it deploys.
+
+**Check.** The run ends `succeeded`. `https://<host>/healthz` answers 200, and `/` redirects to the IAM
+sign-in. A green run proves only that Zerops accepted the build: have the human sign in and use the app.
+
+## Step 6. Upgrade later
+
+```bash
+fabrika platform upgrade --provider=zerops --to=<newer tag> --sidecar=<sidecar checkout>
+```
+
+It commits the tag to the sidecar's `fabrika.ref`, pushes, and follows the workflow run it triggers. It
+needs only the `gh` login. Existing namespaces keep their proxy version. To move one to the proxy of the
+new release, after the run succeeded:
+
+```bash
+fabrika control namespaces update --namespace=<id> --proxy-source=current
+```
+
+It re-pins the namespace and queues the reconcile that rebuilds its proxy; poll `namespaces get` until it is
+`ready`. A namespace pinned to a release before the proxy manifest moved into the build archive carries it in a
+service variable, which Zerops caps at about 32 KB: when a deploy fails with `serviceEnvValueTooLarge`, this is
+the fix, and it also accepts a namespace in `failed`.
+
+## When something fails
+
+- Every refusal names its flag or variable. Fix that one value and re-run. `init`, `admin`, `deploy` and
+  `upgrade` are safe to re-run. `install` is not: see step 1.
+- A failed install pass 2 is finished with `platform deploy`, with the credentials from the secrets file. The
+  install prints the command.
+- Lost the secrets file? Nothing in fabrika can recover it, and Zerops will not hand the values back. Start a
+  new installation in a new project.
+- A Zerops build or deploy failure: read the service log in the Zerops GUI or with
+  `zcli service log -S <service id> --show-build-logs`.
+- Do not work around a refusal by editing the clone or the generated sidecar. Report what failed, with the
+  command and its message, to the people who maintain fabrika.