create-flowdular 0.4.3 → 0.6.0

package/template/default/README.md

@@ -7,13 +7,15 @@ example module, and nothing else you have to configure.
 
 ```bash
 pnpm install
-pnpm flowdular setup
 pnpm dev
 ```
 
-Open <http://localhost:4310> and sign in as `admin@example.com`. Quick setup is
-a destructive local reset: stop `pnpm dev` first, and never point it at a
-deployed database.
+On the first run, the server starts the setup page and `pnpm dev` opens it in
+your browser. Enter the one-time token printed in the terminal, then choose
+your workspace and owner account. The embedded database is already selected.
+If a browser cannot open automatically, visit <http://localhost:4310/setup>.
+Restart `pnpm dev` after setup, then sign in with the account you chose. Use
+`pnpm dev -- --no-open` to leave the browser alone.
 
 Local development runs on embedded PostgreSQL, so there is no database server to
 install. Data lives under `.flowdular/data`.
@@ -25,7 +27,7 @@ install. Data lives under `.flowdular/data`.
 | `platform`        | The deployable composition root and the application shell    |
 | `modules/example` | A tenant-scoped record module: API, migration, screen, tests |
 | `specs`           | The platform spec of this application                        |
-| `infra`           | Dockerfile, compose stack and Kubernetes base                |
+| `infra`           | Docker, Kubernetes and Vercel deployment assets              |
 | `flowdular.json`  | Enabled modules and locales, owned by the CLI                |
 | `.env`            | The keys generated for this app. Never commit it             |
 | `.env.example`    | Every key a production deployment reads                      |
@@ -33,11 +35,13 @@ install. Data lives under `.flowdular/data`.
 ## Work with coding agents
 
 `AGENTS.md` and `CLAUDE.md` introduce the application contract. `.ai` contains the
-editable rules, skills, role prompts, policies, blueprints and reference module.
-Codex and Claude Code discover generated skills in `.agents/skills` and
-`.claude/skills`. Supporting guides are in `docs`.
+editable rules, skills, role prompts, subagents, policies, blueprints and
+reference module. Codex and Claude Code discover generated skills in
+`.agents/skills` and `.claude/skills`, and the spec author, module executor and
+reviewer as subagents in `.codex/agents` and `.claude/agents`. Supporting guides
+are in `docs`.
 
-After editing `.ai/rules` or `.ai/skills`, run `pnpm rules:generate`.
+After editing `.ai/rules`, `.ai/skills` or `.ai/subagents`, run `pnpm rules:generate`.
 `pnpm rules:check` detects drift and also runs as part of `pnpm verify`.
 Extend local modules using the published `@flowdular/sdk` imports. Installed
 SDK source is reference material and must not be edited in `node_modules`.
@@ -77,19 +81,26 @@ account access, then paste the token and the application address into the
 connect screen.
 
 ```bash
-pnpm flowdular sandbox grant --email admin@example.com --tenant operations-demo --apply
+pnpm flowdular sandbox grant --email <your-owner-email> --tenant <your-workspace-slug> --apply
 ```
 
 ## Deploy
 
 ```bash
-cp .env.example infra/docker/.env   # then fill in every value
-docker compose -f infra/docker/compose.yaml up --build
+node infra/docker/start.mjs
 ```
 
-`.env.example` lists every key the server reads in production. `infra/README.md`
-covers the container image, the PostgreSQL roles and TLS, migrations on rollout,
-and the Kubernetes base.
+The launcher creates `infra/docker/.env` with private database passwords and
+keys, starts PostgreSQL and MinIO, then opens the setup page. Enter the token
+shown in the terminal. The database step is already complete, so you start with
+the workspace owner. `infra/README.md` covers the stack and deployments.
+
+To deploy on Vercel, run `vercel login` and then
+`pnpm flowdular deploy start vercel --apply`. It provisions Neon PostgreSQL, a
+private Blob store and the stable keys, deploys, and prints a one-time token for
+creating the first workspace at `/setup`; `infra/vercel/README.md` walks through
+it and the manual path. Module workers run in a worker Function that Vercel Cron
+and state-changing requests tick.
 
 ## Commands
 

package/template/default/_gitignore

@@ -1,8 +1,9 @@
 node_modules/
 dist/
 .flowdular/
-.env
-.env.*
+# vercel link appends these two lines unless they are already here verbatim.
+.vercel
+.env*
 !.env.example
 *.log
 .DS_Store

package/template/default/infra/README.md

@@ -1,5 +1,49 @@
 # Deployment
 
+## Deployment targets
+
+Run `pnpm flowdular deploy targets` to inspect the target contracts and
+`pnpm flowdular deploy plan docker` before starting the local stack.
+`pnpm flowdular deploy start docker --apply` starts Docker Compose and opens
+first-run setup. It prints the setup token, so it requires a private
+interactive terminal and refuses `--json` or redirected output.
+
+The repository-root `render.yaml` is a Render Blueprint for an always-on
+container. It needs external PostgreSQL with separate runtime, background and
+migrator roles, verified TLS and an existing S3 bucket. The Blueprint prompts
+for the database and storage values, derives its public HTTPS origin from the
+Render service and generates encryption keys. Back up those keys separately.
+If you add a custom domain, set its HTTPS origin in `render.yaml` so the next
+Blueprint sync keeps it. It uses
+`/api/health` during initial setup; verify
+`/api/ready` after setup. See the main Flowdular deployment guide for details.
+Render Blueprints can create a database, but `fromDatabase` gives its internal
+URL, whose self-signed TLS certificate cannot satisfy Flowdular's production
+`verify-full` requirement. The Blueprint also cannot declare the three
+separate roles. Render can host MinIO, but this Blueprint does not initialize
+its bucket or wire its credentials. For a store other than AWS S3, set
+`FD_STORAGE_S3_ENDPOINT` and, if needed, `FD_STORAGE_S3_FORCE_PATH_STYLE` on
+the Render service. See the [Render Postgres connection guide](https://render.com/docs/postgresql-creating-connecting)
+and [MinIO guide](https://render.com/docs/deploy-minio).
+After committing
+`render.yaml` and `infra/docker/Dockerfile` and pushing the branch to a
+credential-free Git origin, `deploy plan render --json` returns a Deploy to
+Render URL when both files pass structural checks and match the pushed branch. The URL
+selects that branch for Render, but the external PostgreSQL, storage and secret
+prerequisites still require operator setup. Local Git tracking refs are not
+live provider validation, so confirm that Render can access the branch.
+
+The [Vercel artifact](vercel/README.md) packages the Octane handler and client
+assets as a web Function and a worker Function. [Vercel Functions scale down to zero](https://vercel.com/docs/functions),
+so module workers run only inside ticks from Vercel Cron and from
+state-changing requests. `deploy plan vercel --json` checks its source and
+returns an import URL for a pushed branch. `deploy start vercel --apply`
+provisions Neon PostgreSQL, a private Blob store and the stable keys through the
+Vercel CLI, deploys to Production and prints a one-time token for creating the
+first workspace at `/setup`.
+Cloudflare's Durable Object Container API can keep a process alive, but
+Flowdular has no verified adapter for its restart, secret and rollout lifecycle.
+
 The production artifact is the server built from `platform`. It runs as a
 non-root user and serves two public probes from
 `platform/src/server/health.ts`: `GET /api/health` answers as soon as the
@@ -11,73 +55,50 @@ background roles hold neither `SUPERUSER` nor `BYPASSRLS`, and answers 503 with
 ## Local container
 
 ```bash
-cp .env.example infra/docker/.env   # then fill in every value
-docker compose -f infra/docker/compose.yaml up --build
+node infra/docker/start.mjs
 ```
 
-Compose refuses to start while a key or a database password is empty, and the
-owning module would refuse at boot anyway. The app is published on
-`http://localhost:3000`; set `FD_PORT` to change the host port.
-
-The build stage runs `pnpm install --frozen-lockfile`, so commit
-`pnpm-lock.yaml` before building.
-
-Compose also starts PostgreSQL. A one-shot `postgres-tls` service generates a
-self-signed server certificate for `CN=postgres` on first run, Postgres serves
-TLS with it, and the app verifies it through `FD_DATABASE_TLS_CA_FILE` under
-`verify-full`. First cluster initialization creates three roles:
-`coreloom_migrator` owns the schema, `coreloom_runtime` holds neither
-`SUPERUSER` nor `BYPASSRLS`, so the row-level security tenant tables force
-actually binds the application, and `coreloom_background` serves the
-cross-tenant scheduler poll with no default table grant at all.
-
-Public sign-up is disabled. The session cookie is Secure (`__Host-` prefix)
-because the container expects TLS in front of it. For a plain-HTTP run on a
-workstation set `FD_AUTH_SECURE_COOKIE=false` in `infra/docker/.env`; do not do
-this for anything reachable from a network.
-
-The runtime image contains only `platform/dist` and `platform/package.json`. The
-server bundle imports node built-ins exclusively, so no `node_modules` directory
-ships with it.
+The launcher creates `infra/docker/.env` with owner-only permissions, generates
+PostgreSQL passwords and platform keys once, and keeps them on later runs. It
+starts PostgreSQL, a private MinIO bucket and the app. When the database is
+empty, it opens the first-run setup in the workstation browser and prints the
+one-time setup token in the terminal. Use `--no-open` on a headless host. The
+normal address is `http://localhost:3000`; change `FD_PORT` in the Docker env
+file to use another port. The container binds to `127.0.0.1` by default. A
+generated Compose project name keeps this app's volumes separate from other
+Flowdular projects on the same machine.
+
+The database and object store are connected before the setup page appears, so
+the wizard starts with workspace and owner details. After confirmation, Compose
+restarts the app into the sign-in screen. AI models are optional and can be
+connected in Providers after signing in. Mail remains off until the operator
+sets `FD_AUTH_MAIL_TRANSPORT=smtp`, `FD_AUTH_SMTP_URL` and `FD_AUTH_MAIL_FROM`.
+
+To run Compose directly, copy `infra/docker/.env.example` to
+`infra/docker/.env`, fill every required secret, set
+`FD_AUTH_SECURE_COOKIE=false` for local HTTP, and run
+`docker compose --env-file infra/docker/.env -f infra/docker/compose.yaml up --build`.
+The setup token is in the `app` container logs. Keep that token out of URLs and
+shared logs. For remote access, configure a TLS proxy, `FD_AUTH_PUBLIC_ORIGIN`,
+`FD_BIND_ADDRESS` and secure cookies.
+
+Compose gives the PostgreSQL runtime and background roles neither `SUPERUSER`
+nor `BYPASSRLS`, and the migrator owns the schema. Its TLS certificate is
+created once and verified by the app. The image ships the bundled server and a
+small entrypoint that URL-encodes database passwords before starting it.
+
+Back up the PostgreSQL data and WAL volumes, the MinIO object volume, and
+`infra/docker/.env` together. The env file holds the keys needed to decrypt
+records and objects after restore. `infra/docker/pitr.sh` can create a base
+backup and replay archived PostgreSQL WAL segments; run its `--help` before a
+restore, which requires explicit confirmation and stops the app when requested.
 
 ## Migrations on rollout
 
-Every module owns its migrations and applies them itself, inside a migration
-lease that connects as `FD_DATABASE_MIGRATOR_URL`, the first time its runtime is
-used. A rollout therefore needs no apply step: start the new image and the
-schema catches up under the schema-owning role, while requests keep running as
-the runtime role.
-
-What a rollout should do is fail before the new image serves traffic when an
-already applied migration no longer matches the code being deployed. That is the
-one-shot `migration-check` service in `infra/docker/compose.yaml`: it runs
-`flowdular migration status --json`, reports what is pending, and exits non-zero
-on a checksum mismatch. `app` starts only after it completes successfully.
-
-```bash
-docker compose -f infra/docker/compose.yaml run --rm migration-check
-```
-
-Outside compose, run the same check from a checkout with the deployment's
-`FD_DATABASE_*` values in the environment. On Kubernetes it belongs in a
-pre-upgrade Job or in the pipeline step ahead of `kubectl apply`. After the
-rollout, `flowdular migration verify` should come back clean.
-
-`flowdular migration apply` exists, but it is not part of a rollout. It takes one
-module at a time (`--module <id> --apply`; there is no `--all` flag) and the
-capability is local-only: the runner refuses it unless `FD_ENV` or `NODE_ENV` is
-`development` or `test`. Use it on a workstation against a local database:
-
-```bash
-pnpm flowdular migration status                       # pending work, per module
-pnpm flowdular migration apply --module example.core  # dry run
-pnpm flowdular migration apply --module example.core --apply
-```
-
-Repeat the last two lines for each module `migration status` reports.
-
-Applied migrations are immutable. To change schema, add a numbered migration;
-never edit one the ledger already recorded.
+Module migrations run through the migration role on first use. Applied
+migrations are immutable: add a numbered migration rather than editing one
+that is already in the ledger. Check migration status with the workspace CLI
+before a production rollout, and verify it afterwards.
 
 ## Published image
 
@@ -93,9 +114,9 @@ kubectl create secret generic flowdular-secrets \
   --from-literal=workflowsPayloadKey="$(openssl rand -base64 32)" \
   --from-literal=workflowsCursorKey="$(openssl rand -base64 32)"
 kubectl create secret generic flowdular-database \
-  --from-literal=migratorUrl='postgresql://coreloom_migrator:...@postgres:5432/flowdular' \
-  --from-literal=runtimeUrl='postgresql://coreloom_runtime:...@postgres:5432/flowdular' \
-  --from-literal=backgroundUrl='postgresql://coreloom_background:...@postgres:5432/flowdular'
+  --from-literal=migratorUrl='postgresql://flowdular_migrator:...@postgres:5432/flowdular' \
+  --from-literal=runtimeUrl='postgresql://flowdular_runtime:...@postgres:5432/flowdular' \
+  --from-literal=backgroundUrl='postgresql://flowdular_background:...@postgres:5432/flowdular'
 kubectl apply -k infra/kubernetes
 ```
 

package/template/default/infra/docker/.env.example

@@ -0,0 +1,66 @@
+# node infra/docker/start.mjs creates infra/docker/.env automatically.
+# To use docker compose directly, copy this file and fill every required secret.
+# Never commit the copy. Generate encryption keys with: openssl rand -base64 32
+# Set a different project name for each app so their named volumes cannot mix.
+COMPOSE_PROJECT_NAME=
+FD_AGENT_CREDENTIAL_KEY=
+FD_AGENT_CREDENTIAL_KEY_PREVIOUS=
+FD_AGENT_RUN_GRANT_KEY=
+FD_AUTH_MFA_KEY=
+FD_AUTH_MFA_KEY_PREVIOUS=
+FD_APPROVAL_GRANT_KEY=
+FD_APPROVAL_GRANT_KEY_PREVIOUS=
+FD_AUTOMATIONS_CREDENTIAL_KEY=
+FD_AUTOMATIONS_CREDENTIAL_KEY_PREVIOUS=
+FD_NOTIFICATIONS_SECRET_KEY=
+FD_NOTIFICATIONS_SECRET_KEY_PREVIOUS=
+FD_WORKFLOWS_PAYLOAD_KEY=
+FD_WORKFLOWS_PAYLOAD_KEY_PREVIOUS=
+FD_WORKFLOWS_CURSOR_KEY=
+FD_WORKFLOWS_CURSOR_KEY_PREVIOUS=
+FD_STORAGE_ENCRYPTION_KEY=
+FD_STORAGE_ENCRYPTION_KEY_PREVIOUS=
+FD_CONNECTORS_SECRET_KEY=
+FD_CONNECTORS_SECRET_KEY_PREVIOUS=
+FD_AUDIT_ANCHOR_KEY=
+FD_AUDIT_ANCHOR_KEY_PREVIOUS=
+
+# The default S3-compatible store is the MinIO service in compose.yaml, with a
+# private flowdular bucket. Override these values for an external S3 service.
+# Back up the MinIO object volume with PostgreSQL and this .env file.
+FD_MINIO_ROOT_PASSWORD=
+FD_STORAGE_S3_BUCKET=
+FD_STORAGE_S3_REGION=
+FD_STORAGE_S3_ENDPOINT=
+FD_STORAGE_S3_ACCESS_KEY_ID=
+FD_STORAGE_S3_SECRET_ACCESS_KEY=
+FD_STORAGE_S3_FORCE_PATH_STYLE=true
+
+# PostgreSQL credentials. The superuser only bootstraps the cluster; the app
+# connects as flowdular_runtime and migrates as flowdular_migrator. Newly created
+# passwords are URL-safe hex. Existing passwords are kept as-is.
+FD_POSTGRES_SUPERUSER_PASSWORD=
+FD_DATABASE_MIGRATOR_PASSWORD=
+FD_DATABASE_RUNTIME_PASSWORD=
+FD_DATABASE_BACKGROUND_PASSWORD=
+
+# Outgoing mail. With none, workspace invitations are refused and password reset
+# messages are never delivered. Set smtp and both values below to send them; the
+# URL carries the relay password, so treat this file as a secret.
+FD_AUTH_MAIL_TRANSPORT=none
+FD_AUTH_SMTP_URL=
+FD_AUTH_MAIL_FROM=
+
+# Host port for the published container port 3000.
+FD_PORT=3000
+FD_BIND_ADDRESS=127.0.0.1
+FD_APPLICATION_PATH=/app
+FD_AUTH_PUBLIC_ORIGIN=
+
+# The local launcher writes false for HTTP on a workstation. For a deployment
+# behind TLS, set true and set FD_AUTH_PUBLIC_ORIGIN to its HTTPS origin.
+FD_AUTH_SECURE_COOKIE=
+
+# Prometheus exposition on GET /api/metrics. Leave FD_METRICS unset to keep it off.
+FD_METRICS=false
+FD_METRICS_TOKEN=

package/template/default/infra/docker/Dockerfile

@@ -7,9 +7,17 @@ WORKDIR /workspace
 
 RUN corepack enable && corepack prepare pnpm@11.17.0 --activate
 
+# The image only builds: tests and checks run in CI before a tag is cut. The
+# package store is fetched from the lockfile alone, so this layer is reused
+# until the lockfile changes.
+COPY pnpm-lock.yaml pnpm-workspace.yaml ./
+RUN pnpm fetch
 COPY . .
-RUN pnpm install --frozen-lockfile
-RUN pnpm verify && pnpm build
+RUN pnpm install --frozen-lockfile --offline
+RUN pnpm build
+RUN mkdir -p module-plans \
+	&& if [ ! -f flowdular.modules.lock.json ]; then printf '{"schemaVersion":1,"modules":[]}\n' > flowdular.modules.lock.json; fi \
+	&& if [ ! -f flowdular.module-sources.json ]; then printf '{"schemaVersion":1,"sources":[]}\n' > flowdular.module-sources.json; fi
 
 FROM node:24-bookworm-slim AS runtime
 
@@ -17,21 +25,27 @@ ENV NODE_ENV=production
 ENV PORT=3000
 WORKDIR /app
 
-RUN groupadd --system --gid 1001 flowdular \
-	&& useradd --system --uid 1001 --gid flowdular flowdular \
+RUN groupadd --system --gid 1001 octane \
+	&& useradd --system --uid 1001 --gid octane octane \
 	&& mkdir -p /data \
-	&& chown flowdular:flowdular /data
+	&& chown octane:octane /data
 
 # The server bundle is self-contained: platform/dist/server/entry.js imports
 # only node:* built-ins, so no node_modules (and no devDependencies) ship.
-COPY --from=builder --chown=flowdular:flowdular /workspace/platform/dist ./platform/dist
-COPY --from=builder --chown=flowdular:flowdular /workspace/platform/package.json ./platform/package.json
-
-USER flowdular
+COPY --from=builder --chown=octane:octane /workspace/platform/dist ./platform/dist
+COPY --from=builder --chown=octane:octane /workspace/platform/package.json ./platform/package.json
+COPY --chown=octane:octane infra/docker/app-entrypoint.mjs infra/docker/database-urls.mjs ./infra/docker/
+COPY --from=builder --chown=octane:octane /workspace/flowdular.json ./flowdular.json
+COPY --from=builder --chown=octane:octane /workspace/flowdular.modules.lock.json ./flowdular.modules.lock.json
+COPY --from=builder --chown=octane:octane /workspace/flowdular.module-sources.json ./flowdular.module-sources.json
+COPY --from=builder --chown=octane:octane /workspace/module-plans ./module-plans
+COPY --from=builder --chown=octane:octane /workspace/modules ./modules
+
+USER octane
 EXPOSE 3000
 VOLUME ["/data"]
 
 HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
 	CMD node -e "fetch('http://127.0.0.1:3000/api/health').then(r=>{if(!r.ok)process.exit(1)}).catch(()=>process.exit(1))"
 
-CMD ["node", "platform/dist/server/entry.js"]
+CMD ["node", "--import", "./infra/docker/app-entrypoint.mjs", "platform/dist/server/entry.js"]

package/template/default/infra/docker/app-entrypoint.mjs

@@ -0,0 +1,5 @@
+import { installDatabaseUrls } from './database-urls.mjs';
+
+if (process.env.FD_DATABASE_ADAPTER === 'postgresql') {
+	installDatabaseUrls(process.env);
+}

package/template/default/infra/docker/compose.yaml

@@ -5,6 +5,7 @@ services:
     volumes:
       - ./postgres/tls-init.sh:/tls-init.sh:ro
       - flowdular-postgres-tls:/tls
+      - flowdular-postgres-wal:/var/lib/postgresql/wal-archive
     restart: 'no'
 
   postgres:
@@ -14,10 +15,10 @@ services:
         condition: service_completed_successfully
     environment:
       POSTGRES_DB: flowdular
-      POSTGRES_PASSWORD: ${FD_POSTGRES_SUPERUSER_PASSWORD:?Set FD_POSTGRES_SUPERUSER_PASSWORD in infra/docker/.env (openssl rand -base64 32)}
-      FD_DATABASE_MIGRATOR_PASSWORD: ${FD_DATABASE_MIGRATOR_PASSWORD:?Set FD_DATABASE_MIGRATOR_PASSWORD in infra/docker/.env (openssl rand -base64 32)}
-      FD_DATABASE_RUNTIME_PASSWORD: ${FD_DATABASE_RUNTIME_PASSWORD:?Set FD_DATABASE_RUNTIME_PASSWORD in infra/docker/.env (openssl rand -base64 32)}
-      FD_DATABASE_BACKGROUND_PASSWORD: ${FD_DATABASE_BACKGROUND_PASSWORD:?Set FD_DATABASE_BACKGROUND_PASSWORD in infra/docker/.env (openssl rand -base64 32)}
+      POSTGRES_PASSWORD: ${FD_POSTGRES_SUPERUSER_PASSWORD:?Run node infra/docker/start.mjs or set FD_POSTGRES_SUPERUSER_PASSWORD}
+      FD_DATABASE_MIGRATOR_PASSWORD: ${FD_DATABASE_MIGRATOR_PASSWORD:?Run node infra/docker/start.mjs or set FD_DATABASE_MIGRATOR_PASSWORD}
+      FD_DATABASE_RUNTIME_PASSWORD: ${FD_DATABASE_RUNTIME_PASSWORD:?Run node infra/docker/start.mjs or set FD_DATABASE_RUNTIME_PASSWORD}
+      FD_DATABASE_BACKGROUND_PASSWORD: ${FD_DATABASE_BACKGROUND_PASSWORD:?Run node infra/docker/start.mjs or set FD_DATABASE_BACKGROUND_PASSWORD}
     command:
       - postgres
       - -c
@@ -26,8 +27,21 @@ services:
       - ssl_cert_file=/tls/server.crt
       - -c
       - ssl_key_file=/tls/server.key
+      # Point-in-time recovery: every completed WAL segment is copied into the
+      # archive volume, and a quiet database still ships one every five
+      # minutes. See infra/README.md, "Backups and PITR", for the limits of a
+      # plain cp archive and for the base backup this needs.
+      - -c
+      - wal_level=replica
+      - -c
+      - archive_mode=on
+      - -c
+      - archive_timeout=300
+      - -c
+      - 'archive_command=test ! -f /var/lib/postgresql/wal-archive/%f && cp %p /var/lib/postgresql/wal-archive/%f'
     volumes:
       - flowdular-postgres:/var/lib/postgresql/data
+      - flowdular-postgres-wal:/var/lib/postgresql/wal-archive
       - flowdular-postgres-tls:/tls:ro
       - ./postgres/10-roles.sh:/docker-entrypoint-initdb.d/10-roles.sh:ro
     healthcheck:
@@ -40,29 +54,40 @@ services:
       - no-new-privileges:true
     restart: unless-stopped
 
-  # Rollout gate. Each module applies its own migrations on first use through a
-  # migration lease, so this one-shot run does not apply anything: it reports
-  # what is pending and fails the rollout when an applied migration no longer
-  # matches the checksum of the code being deployed. It needs the workspace and
-  # the CLI, so it runs the builder stage rather than the runtime image.
-  migration-check:
-    build:
-      context: ../..
-      dockerfile: infra/docker/Dockerfile
-      target: builder
-    image: flowdular-app-builder:local
-    depends_on:
-      postgres:
-        condition: service_healthy
-    command: ['pnpm', 'flowdular', 'migration', 'status', '--json']
+  minio:
+    image: minio/minio:RELEASE.2025-09-07T16-13-09Z
+    command: server /data --console-address :9001
     environment:
-      FD_DATABASE_ADAPTER: postgresql
-      FD_DATABASE_URL: postgresql://coreloom_runtime:${FD_DATABASE_RUNTIME_PASSWORD}@postgres:5432/flowdular
-      FD_DATABASE_MIGRATOR_URL: postgresql://coreloom_migrator:${FD_DATABASE_MIGRATOR_PASSWORD}@postgres:5432/flowdular
-      FD_DATABASE_TLS: verify-full
-      FD_DATABASE_TLS_CA_FILE: /tls/server.crt
+      MINIO_ROOT_USER: ${FD_MINIO_ROOT_USER:-flowdularlocal}
+      MINIO_ROOT_PASSWORD: ${FD_MINIO_ROOT_PASSWORD:?Run node infra/docker/start.mjs or set FD_MINIO_ROOT_PASSWORD}
     volumes:
-      - flowdular-postgres-tls:/tls:ro
+      - flowdular-objects:/data
+    security_opt:
+      - no-new-privileges:true
+    restart: unless-stopped
+
+  minio-init:
+    image: minio/mc:RELEASE.2025-08-13T08-35-41Z
+    entrypoint: /bin/sh
+    command:
+      - -ec
+      - |
+        for attempt in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30; do
+          if mc alias set local http://minio:9000 "$$MINIO_ROOT_USER" "$$MINIO_ROOT_PASSWORD" >/dev/null 2>&1; then
+            mc mb --ignore-existing "local/$$FD_STORAGE_S3_BUCKET"
+            exit 0
+          fi
+          sleep 2
+        done
+        echo 'MinIO did not become ready within 60 seconds.' >&2
+        exit 1
+    depends_on:
+      minio:
+        condition: service_started
+    environment:
+      MINIO_ROOT_USER: ${FD_MINIO_ROOT_USER:-flowdularlocal}
+      MINIO_ROOT_PASSWORD: ${FD_MINIO_ROOT_PASSWORD:?Run node infra/docker/start.mjs or set FD_MINIO_ROOT_PASSWORD}
+      FD_STORAGE_S3_BUCKET: ${FD_STORAGE_S3_BUCKET:-flowdular}
     security_opt:
       - no-new-privileges:true
     restart: 'no'
@@ -71,11 +96,11 @@ services:
     build:
       context: ../..
       dockerfile: infra/docker/Dockerfile
-    image: flowdular-app:local
+    image: flowdular:local
     depends_on:
       postgres:
         condition: service_healthy
-      migration-check:
+      minio-init:
         condition: service_completed_successfully
     environment:
       NODE_ENV: production
@@ -83,29 +108,56 @@ services:
       # Every module reads and writes through the platform provider; the
       # deployment has one database and no per-module files.
       FD_DATABASE_ADAPTER: postgresql
-      FD_DATABASE_URL: postgresql://coreloom_runtime:${FD_DATABASE_RUNTIME_PASSWORD}@postgres:5432/flowdular
-      FD_DATABASE_MIGRATOR_URL: postgresql://coreloom_migrator:${FD_DATABASE_MIGRATOR_PASSWORD}@postgres:5432/flowdular
+      # The image entrypoint encodes these passwords before making PostgreSQL
+      # URLs. Older deployments may have generated base64 values containing /.
+      FD_DATABASE_RUNTIME_PASSWORD: ${FD_DATABASE_RUNTIME_PASSWORD:?Run node infra/docker/start.mjs or set FD_DATABASE_RUNTIME_PASSWORD}
+      FD_DATABASE_MIGRATOR_PASSWORD: ${FD_DATABASE_MIGRATOR_PASSWORD:?Run node infra/docker/start.mjs or set FD_DATABASE_MIGRATOR_PASSWORD}
       # Cross-tenant reads (the scheduler poll) run as this role. It carries no
       # blanket grant: a migration hands it named columns under its own policy.
-      FD_DATABASE_BACKGROUND_URL: postgresql://coreloom_background:${FD_DATABASE_BACKGROUND_PASSWORD}@postgres:5432/flowdular
+      FD_DATABASE_BACKGROUND_PASSWORD: ${FD_DATABASE_BACKGROUND_PASSWORD:?Run node infra/docker/start.mjs or set FD_DATABASE_BACKGROUND_PASSWORD}
+      FD_DATABASE_URL: ${FD_DATABASE_URL:-}
+      FD_DATABASE_MIGRATOR_URL: ${FD_DATABASE_MIGRATOR_URL:-}
+      FD_DATABASE_BACKGROUND_URL: ${FD_DATABASE_BACKGROUND_URL:-}
       FD_DATABASE_TLS: verify-full
       FD_DATABASE_TLS_CA_FILE: /tls/server.crt
+      FD_AUTH_PUBLIC_ORIGIN: ${FD_AUTH_PUBLIC_ORIGIN:-http://localhost:${FD_PORT:-3000}}
+      FD_APPLICATION_PATH: ${FD_APPLICATION_PATH:-/app}
+      FD_SETUP_AUTO_RESTART: 'true'
       FD_AUTH_ALLOW_SIGN_UP: 'false'
       # TLS terminates in front of this container. Only a plain-HTTP run on a
       # workstation may set FD_AUTH_SECURE_COOKIE=false in .env.
       FD_AUTH_SECURE_COOKIE: ${FD_AUTH_SECURE_COOKIE:-true}
-      # Every key comes from infra/docker/.env (copy the root .env.example).
-      # Compose refuses to start without them; the owning module would refuse at
-      # boot anyway.
-      FD_AGENT_CREDENTIAL_KEY: ${FD_AGENT_CREDENTIAL_KEY:?Set FD_AGENT_CREDENTIAL_KEY in infra/docker/.env (openssl rand -base64 32)}
-      FD_AGENT_RUN_GRANT_KEY: ${FD_AGENT_RUN_GRANT_KEY:?Set FD_AGENT_RUN_GRANT_KEY in infra/docker/.env (openssl rand -base64 32)}
-      FD_AUTOMATIONS_CREDENTIAL_KEY: ${FD_AUTOMATIONS_CREDENTIAL_KEY:?Set FD_AUTOMATIONS_CREDENTIAL_KEY in infra/docker/.env (openssl rand -base64 32)}
-      FD_NOTIFICATIONS_SECRET_KEY: ${FD_NOTIFICATIONS_SECRET_KEY:?Set FD_NOTIFICATIONS_SECRET_KEY in infra/docker/.env (openssl rand -base64 32)}
-      FD_WORKFLOWS_PAYLOAD_KEY: ${FD_WORKFLOWS_PAYLOAD_KEY:?Set FD_WORKFLOWS_PAYLOAD_KEY in infra/docker/.env (openssl rand -base64 32)}
-      FD_WORKFLOWS_CURSOR_KEY: ${FD_WORKFLOWS_CURSOR_KEY:?Set FD_WORKFLOWS_CURSOR_KEY in infra/docker/.env (openssl rand -base64 32)}
-      FD_STORAGE_ENCRYPTION_KEY: ${FD_STORAGE_ENCRYPTION_KEY:?Set FD_STORAGE_ENCRYPTION_KEY in infra/docker/.env (openssl rand -base64 32)}
-      FD_CONNECTORS_SECRET_KEY: ${FD_CONNECTORS_SECRET_KEY:?Set FD_CONNECTORS_SECRET_KEY in infra/docker/.env (openssl rand -base64 32)}
-      FD_AUDIT_ANCHOR_KEY: ${FD_AUDIT_ANCHOR_KEY:?Set FD_AUDIT_ANCHOR_KEY in infra/docker/.env (openssl rand -base64 32)}
+      FD_AUTH_MFA_KEY: ${FD_AUTH_MFA_KEY:?Run node infra/docker/start.mjs or set FD_AUTH_MFA_KEY}
+      FD_AUTH_MFA_KEY_PREVIOUS: ${FD_AUTH_MFA_KEY_PREVIOUS:-}
+      # Outgoing mail. none refuses invitations and delivers no password reset
+      # message; smtp requires the URL and the sender below.
+      FD_AUTH_MAIL_TRANSPORT: ${FD_AUTH_MAIL_TRANSPORT:-none}
+      FD_TRUST_PROXY: ${FD_TRUST_PROXY:-false}
+      FD_METRICS: ${FD_METRICS:-false}
+      FD_METRICS_TOKEN: ${FD_METRICS_TOKEN:-}
+      FD_AUTH_SMTP_URL: ${FD_AUTH_SMTP_URL:-}
+      FD_AUTH_MAIL_FROM: ${FD_AUTH_MAIL_FROM:-}
+      # start.mjs creates these once in infra/docker/.env. Existing values win.
+      FD_AGENT_CREDENTIAL_KEY: ${FD_AGENT_CREDENTIAL_KEY:?Run node infra/docker/start.mjs or set FD_AGENT_CREDENTIAL_KEY}
+      FD_AGENT_RUN_GRANT_KEY: ${FD_AGENT_RUN_GRANT_KEY:?Run node infra/docker/start.mjs or set FD_AGENT_RUN_GRANT_KEY}
+      FD_APPROVAL_GRANT_KEY: ${FD_APPROVAL_GRANT_KEY:?Run node infra/docker/start.mjs or set FD_APPROVAL_GRANT_KEY}
+      FD_AUTOMATIONS_CREDENTIAL_KEY: ${FD_AUTOMATIONS_CREDENTIAL_KEY:?Run node infra/docker/start.mjs or set FD_AUTOMATIONS_CREDENTIAL_KEY}
+      FD_NOTIFICATIONS_SECRET_KEY: ${FD_NOTIFICATIONS_SECRET_KEY:?Run node infra/docker/start.mjs or set FD_NOTIFICATIONS_SECRET_KEY}
+      FD_WORKFLOWS_PAYLOAD_KEY: ${FD_WORKFLOWS_PAYLOAD_KEY:?Run node infra/docker/start.mjs or set FD_WORKFLOWS_PAYLOAD_KEY}
+      FD_WORKFLOWS_CURSOR_KEY: ${FD_WORKFLOWS_CURSOR_KEY:?Run node infra/docker/start.mjs or set FD_WORKFLOWS_CURSOR_KEY}
+      FD_STORAGE_ENCRYPTION_KEY: ${FD_STORAGE_ENCRYPTION_KEY:?Run node infra/docker/start.mjs or set FD_STORAGE_ENCRYPTION_KEY}
+      FD_CONNECTORS_SECRET_KEY: ${FD_CONNECTORS_SECRET_KEY:?Run node infra/docker/start.mjs or set FD_CONNECTORS_SECRET_KEY}
+      FD_AUDIT_ANCHOR_KEY: ${FD_AUDIT_ANCHOR_KEY:?Run node infra/docker/start.mjs or set FD_AUDIT_ANCHOR_KEY}
+      # Previous keys are operator-managed during rotation and remain empty on a new install.
+      FD_AGENT_CREDENTIAL_KEY_PREVIOUS: ${FD_AGENT_CREDENTIAL_KEY_PREVIOUS:-}
+      FD_APPROVAL_GRANT_KEY_PREVIOUS: ${FD_APPROVAL_GRANT_KEY_PREVIOUS:-}
+      FD_AUTOMATIONS_CREDENTIAL_KEY_PREVIOUS: ${FD_AUTOMATIONS_CREDENTIAL_KEY_PREVIOUS:-}
+      FD_NOTIFICATIONS_SECRET_KEY_PREVIOUS: ${FD_NOTIFICATIONS_SECRET_KEY_PREVIOUS:-}
+      FD_WORKFLOWS_PAYLOAD_KEY_PREVIOUS: ${FD_WORKFLOWS_PAYLOAD_KEY_PREVIOUS:-}
+      FD_WORKFLOWS_CURSOR_KEY_PREVIOUS: ${FD_WORKFLOWS_CURSOR_KEY_PREVIOUS:-}
+      FD_STORAGE_ENCRYPTION_KEY_PREVIOUS: ${FD_STORAGE_ENCRYPTION_KEY_PREVIOUS:-}
+      FD_CONNECTORS_SECRET_KEY_PREVIOUS: ${FD_CONNECTORS_SECRET_KEY_PREVIOUS:-}
+      FD_AUDIT_ANCHOR_KEY_PREVIOUS: ${FD_AUDIT_ANCHOR_KEY_PREVIOUS:-}
       # Object storage. Production refuses the local adapter, so the app writes
       # to an S3-compatible bucket and encrypts every object under
       # FD_STORAGE_ENCRYPTION_KEY before it leaves the process. The named volume
@@ -113,23 +165,14 @@ services:
       # run outside production for a demonstration.
       FD_STORAGE_ADAPTER: ${FD_STORAGE_ADAPTER:-s3}
       FD_STORAGE_LOCAL_DIRECTORY: /var/lib/flowdular/storage
-      FD_STORAGE_S3_BUCKET: ${FD_STORAGE_S3_BUCKET:-}
-      FD_STORAGE_S3_REGION: ${FD_STORAGE_S3_REGION:-}
-      FD_STORAGE_S3_ENDPOINT: ${FD_STORAGE_S3_ENDPOINT:-}
-      FD_STORAGE_S3_ACCESS_KEY_ID: ${FD_STORAGE_S3_ACCESS_KEY_ID:-}
-      FD_STORAGE_S3_SECRET_ACCESS_KEY: ${FD_STORAGE_S3_SECRET_ACCESS_KEY:-}
-      FD_STORAGE_S3_FORCE_PATH_STYLE: ${FD_STORAGE_S3_FORCE_PATH_STYLE:-false}
-      # Optional: without it the app runs and only MFA enrollment is unavailable.
-      FD_AUTH_MFA_KEY: ${FD_AUTH_MFA_KEY:-}
-      # Outgoing mail. With none, invitations and password resets are refused.
-      FD_AUTH_MAIL_TRANSPORT: ${FD_AUTH_MAIL_TRANSPORT:-none}
-      FD_TRUST_PROXY: ${FD_TRUST_PROXY:-false}
-      FD_METRICS: ${FD_METRICS:-false}
-      FD_METRICS_TOKEN: ${FD_METRICS_TOKEN:-}
-      FD_AUTH_SMTP_URL: ${FD_AUTH_SMTP_URL:-}
-      FD_AUTH_MAIL_FROM: ${FD_AUTH_MAIL_FROM:-}
+      FD_STORAGE_S3_BUCKET: ${FD_STORAGE_S3_BUCKET:-flowdular}
+      FD_STORAGE_S3_REGION: ${FD_STORAGE_S3_REGION:-us-east-1}
+      FD_STORAGE_S3_ENDPOINT: ${FD_STORAGE_S3_ENDPOINT-}
+      FD_STORAGE_S3_ACCESS_KEY_ID: ${FD_STORAGE_S3_ACCESS_KEY_ID:-${FD_MINIO_ROOT_USER:-flowdularlocal}}
+      FD_STORAGE_S3_SECRET_ACCESS_KEY: ${FD_STORAGE_S3_SECRET_ACCESS_KEY:-${FD_MINIO_ROOT_PASSWORD:?Run node infra/docker/start.mjs or set FD_MINIO_ROOT_PASSWORD}}
+      FD_STORAGE_S3_FORCE_PATH_STYLE: ${FD_STORAGE_S3_FORCE_PATH_STYLE:-true}
     ports:
-      - '${FD_PORT:-3000}:3000'
+      - '${FD_BIND_ADDRESS:-127.0.0.1}:${FD_PORT:-3000}:3000'
     healthcheck:
       test:
         - CMD
@@ -153,6 +196,10 @@ services:
 
 volumes:
   flowdular-postgres:
+  # WAL segments and base backups for point-in-time recovery (infra/docker/pitr.sh).
+  flowdular-postgres-wal:
   flowdular-postgres-tls:
   # Only the local adapter writes here; a production run uses the S3 bucket.
   flowdular-storage:
+  # Local S3-compatible storage; back up this volume alongside PostgreSQL.
+  flowdular-objects: