cloudfall 0.8.0rc4__tar.gz → 0.8.0rc5__tar.gz

{cloudfall-0.8.0rc4 → cloudfall-0.8.0rc5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cloudfall
-Version: 0.8.0rc4
+Version: 0.8.0rc5
 Summary: The operator's record for self-hosted servers run by an AI agent: Ansible executes, Cloudfall gates, verifies and keeps the receipts
 Project-URL: Homepage, https://cloudfall.dev
 Project-URL: Repository, https://github.com/cloudfall-dev/cloudfall

cloudfall-0.8.0rc5/docs/specs/002-component-build-steps.md

@@ -0,0 +1,137 @@
+# S-002: Component build steps
+
+status: approved
+
+## Problem
+
+A component can't ship a frontend build. `artifact build`
+(`engine/src/cloudfall_engine/artifact.py`) clones the repository at a ref and tars the tree
+(or `repository.subdirectory`) with no build step, so a Vite app's `web/dist/` never reaches
+the artifact. `cloudfall_deploy` (`engine/ansible/roles/cloudfall_deploy/tasks/main.yml`)
+asserts `runtime.type == "python"` and `runtime.packageManager == "uv"` and runs only
+`uv sync` on the server. Abecra (Cloudfall's customer zero) works around it with a side
+script that builds and rsyncs the web app into its own release tree: no digest check, no
+receipt, and no rollback together with the API release (cloudfall-dev/cloudfall#86).
+
+The same issue shows the schema promising more than the engine does: `component.schema.json`
+accepts `runtime.type: node | pm2` and `packageManager: npm | pnpm | yarn`, which pass
+`cloudfall config validate` and then fail in the role.
+
+S-003 (Domain routes) is the pair to this spec: it serves the build output from the
+component's release.
+
+## Behaviour
+
+A Component may declare build steps that run on the controller before packaging:
+
+```yaml
+spec:
+  buildTools:
+    node: "22.0.0"
+    pnpm: "9.0.0"
+  build:
+    - workingDirectory: web
+      command: [pnpm, install, --frozen-lockfile]
+    - workingDirectory: web
+      command: [pnpm, build]
+  artifact:
+    include: [web/dist]
+```
+
+- `spec.build` is an ordered list of steps, each with `workingDirectory` (relative, no `..`,
+  same rule as `repository.subdirectory`), `command` (an argv list, never a shell string) and
+  an optional `timeoutSeconds` (1 to 3600, default 900)
+- `spec.buildTools` maps each tool a step runs to its minimum version, like a command's
+  `required_tools`. Every step's `command[0]` must be a key of `buildTools`; it is looked up
+  on the controller's `PATH`
+- `spec.artifact.include` lists paths (relative, no `..`) that the build produces and the
+  archive must keep, even when the repository's `.gitignore` names them
+- `buildTools`, `build` and `artifact` are optional. `artifact` and `buildTools` require
+  `build`. A Component without `build` validates, builds and deploys exactly as today
+
+`artifact build` with declared steps works in this order:
+
+1. Before cloning, each `buildTools` entry is checked: the tool must be on `PATH`
+   (`artifact_build_tool_missing` otherwise) and `<tool> --version` must print a version at
+   least the declared one (`artifact_build_tool_unsupported` otherwise, also when no version
+   can be read). Both exit `ARTIFACT_BUILD_FAILED` with the code in the error context
+2. The clean checkout is made as today, at the resolved commit
+3. Each step runs in order, in `<packaged root>/<workingDirectory>`, where the packaged root is
+   `repository.subdirectory` when set and the checkout otherwise. A step that exits non-zero
+   or outruns its timeout stops the build with `artifact_build_step_failed`, naming the step
+   index, its argv and its exit code, with the tail of its stderr
+4. Each `artifact.include` path must exist after the last step (`artifact_include_missing`
+   otherwise)
+5. The archive holds the files git tracks at the commit under the packaged root, plus every
+   `artifact.include` path. Other files the build left behind (`node_modules/`, caches) are
+   not packaged. Without `build`, the archive is the tree as today
+
+Any failure in steps 1 to 4 writes no archive and no metadata file. Step output never goes to
+stdout, so `artifact build` still answers one JSON envelope there; it goes to stderr.
+
+Build steps run on the controller (the operator's machine or CI), not on the server, with the
+operator's user and file access. A step runs code from the component's repository
+(`package.json` scripts, install hooks). To limit what that code sees, a step gets only
+`PATH`, `HOME`, `LANG`, `TMPDIR` from the controller's environment plus `CI=true`; cloud
+tokens, SOPS keys and other variables are not passed. The `build_artifact` MCP tool stays
+`mutating`, so an agent can only start a build where the operator's policy allows mutating
+tools.
+
+The Artifact metadata file (`config/schemas/v1/artifact.schema.json`, written by
+`build_artifact`) gains an optional `spec.build` object: `steps` (each step's
+`workingDirectory` and `command` as run) and `tools` (each tool's version as read in step 1).
+Metadata without `build` validates as before, and a build without steps writes none.
+
+The archive is then deployed by `cloudfall_deploy` unchanged: the digest check, the
+`releases/<release>/` unpack, the `current` symlink switch, the receipt, and
+`cloudfall rollback` cover the build output with the rest of the release.
+
+`cloudfall config validate` refuses a Component whose runtime the deploy role can't run: any
+`runtime.type` other than `python` or any `runtime.packageManager` other than `uv`, with
+`component_runtime_unsupported` naming the field and saying only Python with uv deploys
+today. The schema enums keep the other values as reserved. This refuses configs that validate
+today but could never deploy. The Render importer (`sdk/src/cloudfall/importer.py`) records a
+Node service as an unsupported gap and writes no Component for it, instead of writing one
+that `config validate` now refuses.
+
+Touches `engine/src/cloudfall_engine/artifact.py`, `engine/src/cloudfall_engine/cli.py`
+(`artifact build`), `config/schemas/v1/component.schema.json`,
+`config/schemas/v1/artifact.schema.json`, `sdk/src/cloudfall/inventory.py`,
+`sdk/src/cloudfall/validation.py`, `sdk/src/cloudfall/importer.py`, `cloudfall config
+validate`, and the `build_artifact` MCP tool.
+
+## Acceptance criteria
+
+- S-002-1: A Component with `buildTools`, a `pnpm install` and a `pnpm build` step in `web`, and `artifact.include: [web/dist]` passes `cloudfall config validate`; every existing Component without `build` still validates
+- S-002-2: `artifact build --ref <sha>` for that Component produces a tarball containing `web/dist/index.html`, even though the repository's `.gitignore` lists `web/dist`
+- S-002-3: The same tarball contains no `web/node_modules/` entry and contains every file `git ls-files` lists at that commit
+- S-002-4: The metadata file next to the tarball has `spec.build.steps` listing both steps' `workingDirectory` and `command` in order, and `spec.build.tools` with the versions `node --version` and `pnpm --version` printed, and validates against `artifact.schema.json`
+- S-002-5: When a declared build tool is not on `PATH`, `artifact build` exits `ARTIFACT_BUILD_FAILED` with code `artifact_build_tool_missing` naming the tool, and no git clone runs
+- S-002-6: When a declared build tool prints a version older than its `buildTools` minimum, `artifact build` exits `ARTIFACT_BUILD_FAILED` with code `artifact_build_tool_unsupported` naming the tool and both versions
+- S-002-7: A build step that exits non-zero makes `artifact build` exit `ARTIFACT_BUILD_FAILED` with code `artifact_build_step_failed` naming the step and its exit code, and the output directory holds no new `.tar.gz` or `.json` file
+- S-002-8: A step that finishes but leaves an `artifact.include` path missing makes `artifact build` exit `ARTIFACT_BUILD_FAILED` with code `artifact_include_missing` and write no artifact
+- S-002-9: A step that prints to stdout leaves the stdout of `artifact build` a single valid JSON envelope
+- S-002-10: A build step sees `CI=true` and does not see a variable such as `HCLOUD_TOKEN` set in the controller's environment
+- S-002-11: `cloudfall config validate` refuses a step whose `command[0]` is not a key of `buildTools`, a `workingDirectory` or `include` path that is absolute or contains `..`, and `artifact` or `buildTools` declared without `build`
+- S-002-12: `cloudfall deploy` of a built release puts `web/dist/index.html` under `<installRoot>/releases/<release>/`, and `cloudfall rollback` to the previous release makes `<installRoot>/current/web/dist/` that release's files
+- S-002-13: For a Component without `build`, `artifact build` packages the same file list as before this change and writes metadata with no `spec.build` key
+- S-002-14: `cloudfall config validate` on a Component with `runtime.type: node`, `runtime.type: pm2`, or `runtime.packageManager` of `npm`, `pnpm` or `yarn` exits `CONFIG_INVALID` with code `component_runtime_unsupported` naming the field
+- S-002-15: Importing a Render blueprint with a Node web service writes no Component for it and lists the service as an unsupported gap
+
+## Out of scope
+
+- Node runtimes on the server (`runtime.type: node | pm2`, npm, pnpm or yarn installs and a Node process under systemd): a separate feature. Until it ships, S-002-14 refuses those runtimes at validate time rather than in the role
+- Building on the server: the server keeps running only `uv sync`, so build toolchains stay off production hosts
+- Pinning exact tool versions or installing tools: `buildTools` checks minimums like `required_tools`; the operator or CI image provides the tools, and the metadata records the versions that ran
+- Sandboxing build steps (containers, network off): the reduced environment limits what a step sees, not what it can do. Revisit with container runtimes
+- Build steps outside the packaged root (a monorepo root lockfile when `repository.subdirectory` is set): `workingDirectory` stays inside the packaged root so the archive and the build see the same tree
+- A separate `static` component kind with its own artifact: two artifacts for one commit would still need a joint rollback, which one artifact gives for free
+- Build caching between runs: each build starts from a clean checkout
+
+## Decisions relied on
+
+- none
+
+## Issues
+
+## Verification

cloudfall-0.8.0rc5/docs/specs/004-domains-apply.md

@@ -0,0 +1,125 @@
+# S-004: Domains apply
+
+status: approved
+
+## Problem
+
+A declared Domain reaches its server only through `domains.yml`. The CLI runs that playbook
+only inside `cloudfall migrate` (`sdk/src/cloudfall/migrate.py`, steps `domains-http`,
+`dns-verify` and `domains-tls`), and the same plan converges `baseline` and `services` on
+every server first. The `converge_domains` MCP tool runs `domains.yml` without the baseline,
+but it takes no domain argument and connects to every server in `cloudfall_servers`. So an
+operator who may deploy to a server but must not converge its baseline (a server lent from
+another project, cloudfall-dev/cloudfall#87) has no safe way to apply one Domain. The vhost
+and the certificate get written by hand, outside the receipts, and the next `domains.yml`
+run overwrites that vhost with no record of what it replaced.
+
+## Behaviour
+
+Two commands in a new `domains` group:
+
+```
+cloudfall domains apply <domain> [--issue-certificate] [--yes]
+cloudfall domains observe <domain>
+```
+
+`<domain>` is a Domain's `metadata.id`. Both commands validate the project first, as
+`deploy` does. Invalid config exits `CONFIG_INVALID`. A valid config with no Domain of that
+id exits `PRECONDITION` with context code `lifecycle_domain_missing`, the way `deploy`
+refuses an unknown component (`lifecycle_component_missing`). Both refusals happen before
+the inventory render and before any SSH connection.
+
+**domains apply**
+
+- Runs `domains.yml` limited to the Domain's `proxy.server` and to that one Domain. No other host is contacted, and the proxy server renders no other Domain
+- The play runs only the `cloudfall_nginx_site` role, so no baseline, firewall, time, access or service task runs. It is safe on a server whose baseline another project owns
+- `origin.server` gets nothing, even when it differs from the proxy server: `domains.yml` has no origin-side task today, and no playbook reads the rendered `cloudfall_origin_domains` variable
+- Without `--yes` it changes nothing and exits 0 with a plan, like `deploy`: `status: "plan"`, `action: "domains-apply"`, `domain`, `servers` (the proxy server), `wouldRun`, `instruction` and `effect: "would_update"`. The plan runs every controller-side check the run does, the DNS check included
+- With `--yes` it answers `status: "ok"`, `action`, `domain`, `servers`, `receipt` (the receipt path) and `effect: "updated"`
+- `--issue-certificate` checks DNS on the controller first, then runs the role with `cloudfall_domains_issue_certificates` true. The role's own sequence is the one `migrate` relies on: the vhost goes live over HTTP to serve the ACME challenge, certbot issues the certificate by webroot, the vhost is rendered again with TLS, and `certbot.timer` is enabled
+- The DNS check covers `primaryName` and every alias. Each name must resolve to at least one address of the proxy server, computed as `migrate`'s `dns-verify` does (the server address, the names it resolves to, and `network.ipv4`). Otherwise the command exits `PRECONDITION` with context code `domains_dns_unverified`, naming each failing name and what it resolved to
+- A Domain with `edge.mode: proxied` skips the DNS check, as `dns-verify` does, and the answer says `dnsCheck: "skipped-proxied"`. A checked Domain answers `dnsCheck: "verified"`. Without `--issue-certificate` there is no DNS check and no `dnsCheck` value
+- `--issue-certificate` on a Domain with `tls.mode: disabled` exits `PRECONDITION` before any engine step
+- A failed playbook run, such as a vhost that `nginx -t` rejects (the role rolls it back) or a failed issuance, exits `ENGINE_STEP_FAILED`
+- Receipts go to `--deployments` (default `tmp/deployments`), the folder `migrate` and `converge_domains` use
+
+**Receipt**
+
+Every `domains.yml` run keeps writing one `DeploymentReceipt` per Domain at
+`<deployments>/<domain>.json` (`config/schemas/v1/deployment-receipt.schema.json`). Its
+`spec` gains an optional `previousConfigurationSha256`: the sha256 of the file at
+`proxy.configurationPath` before this run rendered it, or `null` when no file was there. The
+role already reads that file before rendering
+(`engine/ansible/roles/cloudfall_nginx_site/tasks/apply_virtual_host.yml`), so it hashes it
+there. The role writes the receipt, so runs from `migrate` and `converge_domains` record the
+field too. A receipt without the field still loads.
+
+**domains observe**
+
+Read-only. It runs a new read-only playbook against the proxy server only, and writes
+nothing to the server or to the project. It reports:
+
+- `server`: the proxy server
+- `vhost`: `path` (`proxy.configurationPath`), `present`, and `sha256` when present
+- `receipt`: `configurationSha256` and `deployedAt` from `<deployments>/<domain>.json`, and `matches` saying whether the vhost on disk has that hash; `null` when there is no receipt
+- `certificate`: `path` (`/etc/letsencrypt/live/<primaryName>/fullchain.pem`), `present`, and `notAfter` when present
+- `certbotTimer`: `enabled` and `active`
+
+It exits 0 whatever it finds: a missing vhost or an expired certificate is a reading, not an
+error. An unreachable server exits `ENGINE_STEP_FAILED`. The playbook hands its reading back
+through a controller-side file, as `backup.yml` does with its receipt. `services observe`
+stays the public-network view of the route; `domains observe` is the server-side view.
+
+**MCP**
+
+`domains.apply` and `domains.observe` join `PROJECT_COMMANDS` in
+`sdk/src/cloudfall/agent_server.py`, so `cloudfall mcp serve` serves them as tools generated
+from the commands. The provided `converge_domains` tool (`_engine_tools` in
+`sdk/src/cloudfall/app.py`) gains an optional `domain` string. Given, the tool runs on that
+Domain's proxy server only and renders only that Domain, with `issue_certificates` working
+as today (no DNS check). An unknown id exits `PRECONDITION`. Omitted, the tool behaves as
+today.
+
+Touches `sdk/src/cloudfall/app.py`, `sdk/src/cloudfall/commands.py`,
+`sdk/src/cloudfall/agent_server.py`, `engine/ansible/playbooks/domains.yml`, a new read-only
+playbook under `engine/ansible/playbooks/`, `engine/ansible/roles/cloudfall_nginx_site`,
+`config/schemas/v1/deployment-receipt.schema.json`, `domains apply`, `domains observe` and
+the `converge_domains` MCP tool.
+
+## Acceptance criteria
+
+- S-004-1: In a project with servers `a` and `b` and a Domain whose `proxy.server` is `a`, `cloudfall domains apply <d> --yes` runs `domains.yml` with only `a` in its play recap, and no task from `baseline.yml`, `services.yml` or the `cloudfall_firewall` role runs
+- S-004-2: With Domains `d1` and `d2` both proxied on `a`, `domains apply d1 --yes` renders only `d1`'s `proxy.configurationPath`, and `d2`'s vhost file and receipt are unchanged
+- S-004-3: Without `--yes`, `domains apply <d>` exits 0 with `status: "plan"` and `effect: "would_update"`, runs no `ansible-playbook`, and writes no receipt
+- S-004-4: `domains apply nope` and `domains observe nope` in a valid project with no Domain `nope` exit `PRECONDITION` with context code `lifecycle_domain_missing`, and neither the inventory render nor `ansible-playbook` runs
+- S-004-5: `domains apply <d>` in a project whose config fails validation exits `CONFIG_INVALID` before any engine step
+- S-004-6: `--issue-certificate` on a `dns-only` Domain with an alias that resolves to no address of the proxy server exits `PRECONDITION` with context code `domains_dns_unverified` naming that alias, with and without `--yes`, and runs no `ansible-playbook`
+- S-004-7: `--issue-certificate` on a `proxied` Domain runs no DNS check and answers `dnsCheck: "skipped-proxied"`
+- S-004-8: `--issue-certificate` on a Domain with `tls.mode: disabled` exits `PRECONDITION` before any engine step
+- S-004-9: `domains apply <d> --issue-certificate --yes` on a fresh `dns-only` Domain whose names resolve to the proxy server passes `cloudfall_domains_issue_certificates: true` to `domains.yml`, ends with `/etc/letsencrypt/live/<primaryName>/fullchain.pem` present and `certbot.timer` enabled and active, answers `dnsCheck: "verified"`, and writes `<deployments>/<d>.json`
+- S-004-10: A second `domains apply <d> --issue-certificate --yes` skips the `Issue the declared certificate` task, and its receipt has `configurationSha256` equal to `previousConfigurationSha256`
+- S-004-11: A `domains.yml` run on a proxy server with a hand-written file at `proxy.configurationPath` writes a receipt whose `previousConfigurationSha256` is that file's sha256, and a run with no file there writes `null`
+- S-004-12: A `DeploymentReceipt` without `previousConfigurationSha256` still loads in `services status`
+- S-004-13: A vhost that `nginx -t` rejects makes `domains apply <d> --yes` exit `ENGINE_STEP_FAILED`
+- S-004-14: `domains observe <d>` reports `vhost.present`, `vhost.sha256`, `certificate.notAfter`, `certbotTimer.enabled` and `certbotTimer.active` as read on the proxy server, exits 0 when the vhost file is missing, and changes no file on the server or in the project
+- S-004-15: `domains observe <d>` reports `receipt.matches: false` once the vhost file was edited after the last receipt, `true` while it is unchanged, and `receipt: null` when no receipt exists
+- S-004-16: `cloudfall mcp serve` on a project lists a tool for `domains apply` and one for `domains observe`
+- S-004-17: The `converge_domains` tool called with `domain: <d>` runs only on `d`'s proxy server and renders only `d`, called without `domain` runs on every server in `cloudfall_servers` as before, and called with an unknown `domain` exits `PRECONDITION`
+
+## Out of scope
+
+- Origin-side tasks: nothing in `domains.yml` acts on `origin.server` today. A spec that adds an origin allowlist or a private upstream can extend `domains apply` to the origin then
+- Opening ports 80 and 443: the firewall belongs to the baseline, which this command must not touch on a lent server. If the firewall blocks them, issuance fails with `ENGINE_STEP_FAILED`
+- Removing a Domain's vhost or certificate: deletion needs its own plan and refusal rules
+- A `--server` flag or several domains per call: one Domain has one proxy server, and a loop over ids covers several
+- Storing `domains observe` readings as evidence files: `services observe` already stores the public view, and the server view can join it later if the dashboard needs it
+- Compatibility of new receipts with an older `cloudfall`: the receipt schema sets `additionalProperties: false`, so an older `services status` refuses a receipt that carries `previousConfigurationSha256`. Upgrading `cloudfall` first is the path, as for any new receipt field
+- `migrate --only domains-http,domains-tls`: a step filter on a resumable plan is easy to get wrong and still reads as a migration
+
+## Decisions relied on
+
+- none
+
+## Issues
+
+## Verification

cloudfall-0.8.0rc5/docs/specs/005-release-command.md

@@ -0,0 +1,128 @@
+# S-005: Release command
+
+status: approved
+
+## Problem
+
+`cloudfall deploy` runs the `cloudfall_deploy` role, which unpacks the release, runs
+`uv sync --frozen --no-dev`, switches `current`, restarts the unit and gates on the health
+check (`engine/ansible/roles/cloudfall_deploy/tasks/main.yml`). Nothing runs a declared
+command against the new release before traffic moves to it, and
+`config/schemas/v1/component.schema.json` has no field for one: `service.command` is the
+only command a component declares. Database migrations therefore run by hand over SSH after
+the health gate (cloudfall-dev/cloudfall#88). The gate checks code against the old schema, a
+failed migration leaves no receipt and stops nothing, and the migration's environment is
+assembled by hand instead of from the unit's `EnvironmentFile`. This spec pairs only loosely
+with S-004: the two share the plan and receipt shape, nothing else.
+
+## Behaviour
+
+A component may declare a release command:
+
+```yaml
+spec:
+  release:
+    command: [.venv/bin/alembic, upgrade, head]
+    workingDirectory: services/api
+    timeoutSeconds: 300
+```
+
+- `command` is required, a non-empty list of non-empty strings like `service.command`. A relative first element resolves against the new release directory, as the unit resolves `service.command` against `current`
+- `workingDirectory` is optional, a relative path inside the release directory with no `..` segment (the rule `repository.subdirectory` follows). It defaults to the release directory itself
+- `timeoutSeconds` is optional, an integer from 1 to 1800, default 300. The bound stays well under `STEP_TIMEOUT_SECONDS` (3600), the limit on the whole playbook run
+- A component without `release` deploys exactly as today
+
+**When it runs**
+
+The `cloudfall_deploy` role runs the command after `Materialize locked dependencies for the
+release` and before `Install the managed service unit`, so before `current` moves and before
+the unit file changes. It runs:
+
+- as the application's `linuxUser` (`application_user` in the rendered inventory)
+- in `<installRoot>/releases/<release>`, or in `workingDirectory` under it
+- with the environment the unit gets: `<installRoot>/shared/env/<component>.env`, the file the unit names in `EnvironmentFile=-` and that `deploy --env-file` installs. The file is parsed by systemd's own rules (for example a transient `systemd-run` unit with the same `EnvironmentFile=`), so quoting means what it means for the service. A missing file gives no extra variables, as for the unit. The variables from `environment` and `secretRefs` are there when the operator rendered them with `secrets render` and passed the file to this or an earlier deploy
+
+**Once per deploy**
+
+`deploy.yml` walks `cloudfall_servers` one host at a time (`serial: 1`, `any_errors_fatal`)
+in inventory order, which need not be `deployment.servers` order. The release server is the
+first entry of `deployment.servers`. The deploy runs that server first, and the command runs
+there only. The other servers deploy afterwards, one at a time as today, and skip the
+command. So the command has run before any server's `current` moves.
+
+The command must be safe while the old release still serves traffic: the other servers, and
+the release server itself until its switch, run old code against whatever the command
+changed. Migrations should be expand and contract: add first, remove in a later release. A
+later failure (a health gate on the second server, say) does not undo what the command did.
+
+**Failure**
+
+A non-zero exit, or a run still going after `timeoutSeconds` (it is then stopped), fails the
+release server's play. Because the play is `any_errors_fatal`, no server switches `current`,
+no unit file changes, and no service restarts. `deploy --yes` exits `ENGINE_STEP_FAILED`, and
+its `error.message` names the release command, its exit code or the timeout, and the end of
+its output. The unpacked release directory stays, as any unpacked release does. No release
+receipt is written: a `ReleaseReceipt` means a release went live (`healthCheckPassed` is
+`const: true`).
+
+**Receipt**
+
+`ReleaseReceipt` (`config/schemas/v1/release-receipt.schema.json`) gains an optional
+`spec.releaseCommand` object:
+
+- `server`: the server the command ran on
+- `command` and `workingDirectory`, as declared
+- `exitCode`: 0
+- `outputTail`: the last 2000 characters of its combined stdout and stderr, the bound `lifecycle.py` already uses for step output, with `maxLength: 2000` in the schema
+
+Every receipt the deploy writes carries the same `releaseCommand`, the one from the release
+server, so the receipt left at `<releases>/<component>.json` names where the command ran
+whichever server wrote it last. A deploy of a component without `release` writes no
+`releaseCommand`. Nothing in the SDK loads release receipts today, so an older `cloudfall`
+is not affected.
+
+**Plan and rollback**
+
+- `deploy` without `--yes` adds `releaseCommand` to its plan: `command`, `workingDirectory`, `timeoutSeconds` and `server` (the release server), or `null` when the component declares none. Its `wouldRun` says the command runs once on that server before any switch
+- `rollback` never runs the release command: downgrades stay a human decision. For a component that declares one, the `rollback` plan's `wouldRun` says the release command is not run and adds `releaseCommandSkipped: true`
+- `restart` never runs it either
+- `migrate`'s `deploy:<component>` steps go through the same deploy, so they run the command
+
+Touches `config/schemas/v1/component.schema.json`,
+`config/schemas/v1/release-receipt.schema.json`, `sdk/src/cloudfall/inventory.py`,
+`sdk/src/cloudfall/validation.py`, `sdk/src/cloudfall/lifecycle.py`,
+`sdk/src/cloudfall/commands.py`, `engine/src/cloudfall_engine/ansible_inventory.py`,
+`engine/ansible/playbooks/deploy.yml`, `engine/ansible/roles/cloudfall_deploy`, `deploy`,
+`rollback` and the MCP tools generated from them.
+
+## Acceptance criteria
+
+- S-005-1: A component with `release.command` that creates a table deploys with `cloudfall deploy --yes`, the table exists afterwards, and the release receipt has `releaseCommand` with the command, `exitCode: 0` and an `outputTail`
+- S-005-2: The command runs after the `Materialize locked dependencies for the release` task and before the `Install the managed service unit` and `Switch the current release symlink` tasks, as the application's `linuxUser`, with the new release directory (or its `workingDirectory`) as its working directory
+- S-005-3: A release command that prints every variable sees each key of the installed `<installRoot>/shared/env/<component>.env`, values with the same quoting rules the unit applies
+- S-005-4: A release command that exits 1 makes `deploy --yes` exit `ENGINE_STEP_FAILED` with an `error.message` naming the release command and exit code 1; `current` still points at the previous release on every server, the unit file is unchanged, the service was not restarted, and no release receipt was written
+- S-005-5: A release command still running after `timeoutSeconds` is stopped and fails the deploy the same way, with an `error.message` naming the timeout
+- S-005-6: With `deployment.servers: [b, a]`, the command runs once, on `b`, before either server's `current` moves, and every release receipt from that deploy names `b` in `releaseCommand.server`
+- S-005-7: `releaseCommand.outputTail` holds at most the last 2000 characters of a command that prints more
+- S-005-8: `deploy` without `--yes` exits 0, shows `releaseCommand` with `command`, `workingDirectory`, `timeoutSeconds` and `server`, and runs no `ansible-playbook`; for a component without `release` it shows `releaseCommand: null`
+- S-005-9: `rollback` of a component with `release` runs no release command, and its plan without `--yes` shows `releaseCommandSkipped: true`
+- S-005-10: A component without `release` deploys with the same Ansible tasks as before and a receipt with no `releaseCommand`
+- S-005-11: `config validate` exits `CONFIG_INVALID` for a `release.workingDirectory` that is absolute or contains `..`, an empty `release.command`, or a `timeoutSeconds` outside 1 to 1800
+
+## Out of scope
+
+- A post-switch hook: the issue's case needs the schema before the gate, and a hook after it can be its own spec
+- Running the command on rollback, or a down command: downgrades stay a human decision, as the issue asks
+- A failure receipt: a `ReleaseReceipt` means a live release, and its schema says so with `healthCheckPassed: true`. The failure's evidence is the `ENGINE_STEP_FAILED` message. A spec for failed-run records can add one for every engine step at once
+- Redacting `outputTail`: the command is the operator's own and runs with secrets in its environment. A command that prints secrets puts them in a receipt under the project, so it should not print them
+- `cloudfall run <component> -- <command>` for one-off commands: useful on its own, but it leaves ordering with the deploy to the operator
+- Runtimes other than Python with uv: the deploy role supports only those today
+- Choosing the release server by anything but its place in `deployment.servers`: the first entry is explicit and needs no new field
+
+## Decisions relied on
+
+- none
+
+## Issues
+
+## Verification

cloudfall-0.8.0rc5/docs/specs/006-standalone-postgresql.md

@@ -0,0 +1,140 @@
+# S-006: Standalone PostgreSQL
+
+status: approved
+
+## Problem
+
+A PostgreSQL `Service` can only hold databases that belong to an application Cloudfall
+deploys. `config/schemas/v1/service.schema.json` requires
+`spec.postgresql.databases[].application`, `cloudfall config validate` refuses a name with
+no `Application` behind it (`sdk/src/cloudfall/validation.py`), and an `Application` needs
+at least one component. The database role is the application's Linux user
+(`_postgres_database` in `sdk/src/cloudfall/inventory.py`), it has no password, and the
+server listens on `127.0.0.1` only (`bind.address` is `const` in the schema and asserted by
+`cloudfall_postgresql`). So a team that wants Cloudfall to run only its database, with the
+app staying elsewhere, has no way to declare it (cloudfall-dev/cloudfall#81).
+
+## Behaviour
+
+**A database with an owner instead of an application.** Each entry of
+`spec.postgresql.databases` names exactly one of `application` (today's form) or `owner`,
+a PostgreSQL role Cloudfall creates. `owner` uses the database-name pattern
+(`^[a-z][a-z0-9_]*$`, at most 63 characters). An entry with `owner` also names
+`passwordRef`, the role's password in the secrets store:
+`{environment, path, key}`, read from `<secrets-dir>/<environment><path>.env` as the line
+`<key>=<value>`, the same sops and age layout `cloudfall secrets render` reads
+(`sdk/src/cloudfall/secrets.py`). An entry with `application` can't carry `passwordRef`.
+A project with a server and a PostgreSQL `Service` whose databases all name an `owner`
+needs no `Application` or `Component`.
+
+`cloudfall config validate` refuses with `CONFIG_INVALID`:
+
+- an entry with both `application` and `owner`, or with neither
+- `owner` without `passwordRef`, or `passwordRef` next to `application`
+- an `owner` of `postgres`, of the metrics role (`alloy`), or equal to the Linux user of an
+  `Application` that has a database on the same service, with code
+  `service_database_owner_reserved`
+
+**The role and its password.** `cloudfall_postgresql` creates the `owner` role with
+`LOGIN` like an application role today, then sets its password on every converge, so a
+rotation is a commit in the secrets repository and a services converge. The value is
+decrypted on the controller by the path that runs `services.yml` (the `converge_services`
+MCP tool, the `services` step of `cloudfall migrate`, the operator's `converge-services`
+operation, and `cloudfall-engine playbook run services.yml`), each reading the secrets
+directory from a `--secrets-dir` flag (default `secrets`, as `secrets render` and
+`mcp serve` use). It reaches the host in a `0600` file removed after the run, the role
+sends it to `psql` on stdin with `no_log`, and PostgreSQL stores it as SCRAM. The value
+never appears in the rendered inventory, a command line, Ansible output, a command's
+answer, or a receipt; the answer names the reference, the key, and the value's SHA-256,
+as `EnvironmentReceipt` does for environment files. A missing file or key stops the run
+with `PRECONDITION` naming the expected path and key before any playbook starts.
+
+**A way in for an outside app.** `spec.postgresql.remoteAccess` is optional:
+
+```yaml
+remoteAccess:
+  listenAddress: 10.0.0.2
+  allowedSources:
+    - 10.0.0.0/24
+```
+
+`listenAddress` is one IPv4 or IPv6 address on the server, never a wildcard.
+`allowedSources` is a non-empty list of CIDRs. `bind` keeps its loopback contract, and the
+same `bind.port` serves both addresses. With `remoteAccess` declared:
+
+- `cloudfall.conf` sets `listen_addresses = '127.0.0.1,<listenAddress>'` and `ssl = on`
+  with the Debian `ssl-cert` snakeoil pair, which the role installs
+- `pg_hba.conf` gains a block between Cloudfall markers with one
+  `hostssl <database> <owner> <cidr> scram-sha-256` line per `owner` database and source.
+  `hostssl` means a remote client must use TLS; a plain connection matches no line and is
+  refused. Databases named by `application` get no line and stay socket-only with peer
+  authentication
+- the server's nftables ruleset gains one rule per source, `ip saddr <cidr> tcp dport
+  <port> accept` (`ip6 saddr` for an IPv6 CIDR), rendered by
+  `engine/src/cloudfall_engine/ansible_inventory.py` into `cloudfall_firewall.allowedInbound`
+  as entries with an optional `sources` list, and applied when `baseline.yml` runs. Entries
+  without `sources` render as today
+
+`cloudfall config validate` refuses `remoteAccess` with `CONFIG_INVALID` when no database
+on the service names an `owner` (`service_remote_access_unused`), when the server's server
+type declares no `firewall` (`service_remote_access_unfirewalled`), when that firewall's
+`allowedInbound` already opens the service port to everyone
+(`service_remote_access_port_open`), or when a source is `0.0.0.0/0` or `::/0`
+(`service_remote_access_open`). With `remoteAccess` absent, PostgreSQL listens on
+`127.0.0.1` only, `pg_hba.conf` keeps no Cloudfall block (a block left by an earlier
+declaration is removed), and no PostgreSQL rule is added to nftables. Closed is the default.
+
+**Backups, the restore drill, and `data copy`.** They don't change. `backup.sh.j2` and
+`restore-check.sh.j2` loop over `postgresql.databases` by `name` only, and
+`cloudfall_data_migration` selects the entry by name and restores with
+`--role <owner>`; its receipt records `service`, `database`, and `owner`, never an
+application. An `owner` database is backed up, drilled, and copied into the same way.
+
+**Compatibility.** Every config that validates today validates the same. A database entry
+with `application` renders exactly as before; one with `owner` renders `name` and `owner`
+with no `application` key. The role's argument spec
+(`engine/ansible/roles/cloudfall_postgresql/meta/argument_specs.yml`) makes `application`
+optional and adds `remoteAccess`. The rendered service carries `passwordRef`, never the value;
+the password travels as its own role variable.
+
+Touches `config/schemas/v1/service.schema.json`, `sdk/src/cloudfall/validation.py`,
+`sdk/src/cloudfall/inventory.py` (`PostgresDatabase`, `_postgres_database`,
+`ServiceInventory`), `sdk/src/cloudfall/secrets.py`, `sdk/src/cloudfall/migrate.py`,
+`sdk/src/cloudfall/app.py` (`converge_services`, `cloudfall migrate`),
+`sdk/src/cloudfall/operator.py`, `engine/src/cloudfall_engine/ansible_inventory.py`,
+`engine/src/cloudfall_engine/cli.py` (`playbook run`),
+`engine/ansible/roles/cloudfall_postgresql`, `engine/ansible/roles/cloudfall_firewall`,
+`engine/ansible/playbooks/services.yml`, and `docs/secrets-guide.md`.
+
+## Acceptance criteria
+
+- S-006-1: A project with one `Server`, its server type, and one PostgreSQL `Service` whose only database declares `owner: billing` and a `passwordRef`, and no `Application` or `Component`, passes `cloudfall config validate` with exit 0
+- S-006-2: A database entry with both `application` and `owner` fails `cloudfall config validate` with `CONFIG_INVALID` naming `spec.postgresql.databases[0]`, and an entry with neither fails the same way
+- S-006-3: `owner` without `passwordRef` fails `cloudfall config validate` with `CONFIG_INVALID`, and so does `passwordRef` next to `application`
+- S-006-4: An `owner` of `postgres`, of `alloy`, or equal to the Linux user of an `Application` with a database on the same service fails with `CONFIG_INVALID` code `service_database_owner_reserved`
+- S-006-5: After `services.yml` converges the service of S-006-1, `pg_roles` holds `billing` with `rolcanlogin` and a `SCRAM-SHA-256` password, and database `billing` is owned by `billing`
+- S-006-6: The password value appears in none of the rendered inventory, the playbook output, the command's answer, or any receipt, and the answer names the reference, the key, and the value's SHA-256
+- S-006-7: A `passwordRef` whose file or key is missing stops the services converge with `PRECONDITION` naming the expected path and key, and no playbook runs
+- S-006-8: With `remoteAccess` of `listenAddress: 10.0.0.2` and `allowedSources: [10.0.0.0/24]`, the converged `cloudfall.conf` reads `listen_addresses = '127.0.0.1,10.0.0.2'` and `ssl = on`, the Cloudfall block in `pg_hba.conf` holds exactly `hostssl billing billing 10.0.0.0/24 scram-sha-256`, and the rendered nftables ruleset holds `ip saddr 10.0.0.0/24 tcp dport 5432 accept` and no unrestricted rule for port 5432
+- S-006-9: On a proving pair of hosts, `psql` from an address in `allowedSources` as `billing` with `sslmode=require` connects, from an address outside it gets no connection, and from an allowed address with `sslmode=disable` is refused with `no pg_hba.conf entry`
+- S-006-10: Removing `remoteAccess` and converging baseline and services leaves `listen_addresses = '127.0.0.1'`, no Cloudfall block in `pg_hba.conf`, and no rule for the service port in nftables
+- S-006-11: `remoteAccess` fails `cloudfall config validate` with `CONFIG_INVALID` and code `service_remote_access_unused` when no database names an `owner`, `service_remote_access_unfirewalled` when the server type declares no `firewall`, `service_remote_access_port_open` when its `allowedInbound` opens the service port, and `service_remote_access_open` for a source of `0.0.0.0/0` or `::/0`
+- S-006-12: For the project in `config/examples`, `cloudfall-engine inventory render` writes a byte-identical inventory before and after the change, and the rendered `cloudfall.conf`, `nftables.conf`, backup script, and restore-check script are identical
+- S-006-13: For the service of S-006-1, the backup script writes `billing-<timestamp>.dump`, the restore drill restores it and passes, and `cloudfall data copy <service> --database billing --source-url-file <file> --yes` restores as role `billing` and writes a receipt with `spec.owner` of `billing`
+
+## Out of scope
+
+- Managed connection pooling (PgBouncer): a separate service with its own auth file, and nothing in the issue needs it yet
+- Replication and read replicas: a different durability contract from the dump-based backup and drill
+- A CA-verified server certificate: the snakeoil pair gives encryption with `sslmode=require`, not server identity with `verify-full`. A later spec can take a certificate from the domain's ACME issuance
+- A tunnel (WireGuard or SSH) as the way in: the listen address plus source list covers a private network and a fixed egress address, which is what the proving run will use
+- Remote access for databases named by `application`: their role has no password and peer authentication is the point of that form
+- Restoring the "for an app elsewhere" path in `docs/neon-migration-guide.md`: it follows a proving run of S-006-9, not this spec
+
+## Decisions relied on
+
+- none
+
+## Issues
+
+## Verification