> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/docs/deployment.md). # Deployment ## Local Development ```bash npm install npm run dev curl http://127.0.0.1:2468/health ``` The root `npm run dev` script starts the local server and web client together. ## Production Status | Component | Deployment status | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `apps/server` | Self-hostable Node process; no production host or deploy workflow is configured. | | `apps/web` | Buildable Vite app; no production app host is configured. | | `apps/warroom` | Deployed to Cloudflare Workers as `factionos-warroom`; custom Worker domain `https://warroom.faction-os.com/`; `workers.dev` URL `https://factionos-warroom.apex-web-services-llc-0d4.workers.dev/`. Cloudflare WAF posture is documented in `docs/runbooks/cloudflare-waf.md`. | | `public-demo` | Officially deployed to Cloudflare Pages project `factionos-public-demo` by `.github/workflows/public-demo-deploy.yml`, with manual Wrangler upload as fallback. Production URL: `https://demo.faction-os.com/`. | | `public-website` | Static Astro workspace for the main `faction-os.com` website. Cloudflare Pages is the configured deployment path through `.github/workflows/public-website-deploy.yml`, with deploy-only credentials and manual Wrangler upload fallback. Production URL expectation: `https://faction-os.com/`. | | Public docs website | Hosted externally on GitBook at `https://faction-os.gitbook.io/faction-os-docs`. | | Hosted auth and persistence | Planned, not configured. | | Analytics | Optional browser Umami sender in `apps/web`; local self-hosted verification is documented in `docs/runbooks/local-umami-analytics.md`, but no production app host or Umami deployment is configured by this repo. | | Push, remote access, and tunnels | Planned or unavailable guardrails only; no Web Push backend, VAPID runtime, Cloudflare Tunnel, remote gateway, or hosted diagnostic agent is deployed. | Phase 07 Session 01 adds hosted-service guardrail artifacts under `.spec_system/archive/phases/phase_07/`, but it does not configure a production app host, hosted auth, hosted storage, analytics, push, remote access, public replay hosting, hosted diagnostics, or trusted erasure. Deploy-only credentials remain limited to Cloudflare Pages/Worker operation and must not become browser config or local development requirements. Phase 13 adds the shipped static `public-website` workspace. It is a local Astro build target with package-local typecheck and build scripts. The workspace does not add server rendering, hosted auth, hosted storage, analytics, or form handling requirements to the core repo. Phase 16 adds the main public website Cloudflare Pages deployment path. The site remains a static Astro output deployed from `public-website/dist`; this is not an `@astrojs/cloudflare` adapter, server rendering, hosted forms, auth, CMS, runtime personalization, analytics, hosted identity, hosted storage, or production app-shell deployment. It also does not configure production hosts for `apps/server` or `apps/web`; those rows remain self-hostable or buildable only until a separate app deployment session changes them. Phase 07 Session 02 adds source-backed hosted config posture only. The local server exposes `GET /diagnostics/hosted-config` for status-only diagnostics; the route reports categories, exposure labels, status labels, counts, and docs paths without raw values. It is not a hosted readiness upload and does not require Supabase, Umami, VAPID, Cloudflare credentials, Worker URLs, tunnel tokens, provider keys, analytics, push, hosted storage, public replay hosting, or remote access for local development. Phase 07 Session 03 adds hosted identity guardrails only. The local server exposes `GET /diagnostics/hosted-identity` for planned or unavailable posture, but no production app host, OAuth provider, SSO provider, Supabase auth client, organization management, account UI, billing, hosted account storage, or account-backed audit trail is deployed. Worker deploy success, Worker health, Cloudflare domain state, and browser Worker URLs are not hosted identity proof. Phase 07 Session 04 adds hosted persistence and public replay guardrails only. The local server exposes `GET /diagnostics/hosted-persistence` for planned or unavailable posture, but no Supabase runtime, database, bucket, migration, upload endpoint, public replay route, takedown runtime, retention service, deletion workflow, or account-backed storage is deployed. Worker health, Cloudflare domains, public demo deploys, and local diagnostics are not storage, public replay, retention, deletion, takedown, production-hosted validation, or trusted erasure proof. Phase 07 Session 06 adds push, remote access, tunnel, and operator diagnostics guardrails only. The local server exposes `GET /diagnostics/hosted-operations` for planned or unavailable posture, but no push backend, push subscription store, VAPID private key use, Cloudflare Tunnel, remote access gateway, remote executor, hosted diagnostic agent, production-hosted validation, or trusted erasure workflow is deployed. Worker deploy success, Pages deploys, custom domains, Cloudflare placeholders, and local diagnostics are not proof of active push delivery, remote access, tunnels, hosted agents, production validation, or erasure. Phase 08 Session 05 adds a repeatable production-hosted smoke command without activating any new hosted service: ```bash npm run release:hosted-smoke npm run release:hosted-smoke -- --json npm run release:hosted-smoke -- --no-network --json ``` The command validates the public demo Pages surface, the War Room Worker custom domain health endpoint, the War Room Worker workers.dev health endpoint, and an optional app shell only when an explicit app host is configured. Output is sanitized to target ids, labels, safe hostnames, docs paths, statuses, booleans, timing buckets, and issue codes. It must not print raw URLs with query strings, Cloudflare account ids, zone ids, API tokens, request bodies, room payloads, prompts, local paths, exports, logs, backups, replay buffers, or raw dashboard output. Cloudflare managed WAF and zone rate-limit rules are dashboard-managed. Use `docs/runbooks/cloudflare-waf.md` for the current preferred rule set and manual validation checklist. When no production app host is configured, `app-shell` is an unavailable no-claim result, not a local workflow failure. `--no-network` is also an explicit no-claim summary mode. Local, mocked, same-origin, CI-only, and documentation-only evidence must not be treated as production-hosted evidence. The sanitized evidence record lives in `.spec_system/archive/phases/phase_08/production_hosted_validation_evidence.md`. Phase 08 Session 08 reran the smoke command as part of release-candidate closeout. `npm run release:hosted-smoke -- --no-network --json` passed as credential-free unavailable/no-claim evidence. The live `--json` run did not clear deployed release claims: public demo reported `SENSITIVE_OUTPUT`, both War Room Worker targets reported `WORKER_DEPLOYMENT` and `WORKER_HEALTH_RATE_LIMIT`, and `app-shell` remained `TARGET_UNAVAILABLE`. Cloudflare deployment remediation was not available in the local closeout environment because deploy credentials were absent. Do not describe the deployed public demo, deployed Worker, or production app shell as release validated until a later safe hosted smoke passes. Follow-up source remediation on 2026-05-31 removed prompt-shaped fields from the checked-in public demo artifact and added a regression check that runs the hosted smoke scanner against `public-demo/index.html` and `public-demo/sw.js`. The checked-in War Room Worker source already emits compact rate-limit and deployment metadata, and a Wrangler dry-run packages those bindings. These changes do not update live Cloudflare Pages or Worker deployments by themselves; rerun the deploy commands below from an authorized environment and then rerun `npm run release:hosted-smoke -- --json` before claiming deployed validation. ## Build Commands ```bash npm run build --workspaces --if-present npm --workspace apps/web run preview npm --workspace apps/server run start ``` `apps/server run start` expects `apps/server/dist` from a prior TypeScript build. ## CI/CD Workflows | Workflow | Path | Trigger | Purpose | | --------------------- | --------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Quality | `.github/workflows/quality.yml` | Main pushes, PRs, manual | Format check, lint, workspace typecheck on Node 26.2.0. | | Tests | `.github/workflows/test.yml` | Main pushes, PRs, manual | Workspace typecheck and Vitest coverage on Node 26.2.0. | | Security | `.github/workflows/security.yml` | Main pushes, PRs, weekly schedule, manual | Secret scan, `npm audit --audit-level=moderate`, dependency review on PRs, and CodeQL. CodeQL SARIF uploads only when Advanced Security is available; otherwise SARIF is retained as an artifact. | | E2E | `.github/workflows/e2e.yml` | Main pushes, PRs, manual | Playwright app and public-demo smoke coverage after separate API, Vite, and static-demo readiness checks. The app server uses mock events for deterministic clean-run cockpit data. | | Release | `.github/workflows/release.yml` | Tag pushes, manual | Runs release gates and creates GitHub release notes from `v*` tags. | | Deploy | `.github/workflows/deploy.yml` | Main pushes, manual | Repo-wide deployment placeholder until a production target is configured. | | War Room deploy | `.github/workflows/warroom-deploy.yml` | Main pushes, manual | Deploys `apps/warroom` to Cloudflare Workers with Wrangler and Cloudflare secrets. | | Public demo deploy | `.github/workflows/public-demo-deploy.yml` | Public demo changes on main, manual | Runs static public-demo gates, deploys `public-demo/` to Cloudflare Pages with Wrangler and Cloudflare secrets, then runs sanitized hosted smoke for the public demo. | | Public website deploy | `.github/workflows/public-website-deploy.yml` | Public website changes on main, manual | Runs `@factionos/public-website` typecheck, build, and built-site checker gates, deploys `public-website/dist` to Cloudflare Pages when deploy credentials are configured, then runs a bounded homepage smoke. | | Pages | `.github/workflows/pages.yml` | Changes to `public-demo/`, manual | Legacy/fallback GitHub Pages deployment for the static public demo when repository Pages is enabled; the workflow now exits cleanly when Pages is disabled. | The official `public-demo` Cloudflare Pages deployment uses the repository workflow `.github/workflows/public-demo-deploy.yml`. The current Pages project is `factionos-public-demo`, and `demo.faction-os.com` is attached as an active custom domain. The workflow expects repository secrets `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`; the optional repository variables `CLOUDFLARE_PAGES_PROJECT_NAME` and `FACTIONOS_PUBLIC_DEMO_URL` can override the default project and smoke URL. The workflow runs `npm run media:gates:check`, `npm run media:demo:check`, and `npm run battlefield:check` before upload, then runs `npm run release:hosted-smoke -- --target public-demo` after deploy. The Cloudflare Pages project does not need to be connected to a Git provider. Manual fallback from an authorized environment remains: ```bash CLOUDFLARE_ACCOUNT_ID= npx wrangler pages deploy public-demo \ --project-name=factionos-public-demo \ --branch=main \ --commit-hash="$(git rev-parse HEAD)" \ --commit-message="$(git log -1 --pretty=%s)" ``` If the Pages project is later connected to Git, use `main` as the production branch, `exit 0` as the build command, and `public-demo` as the build output directory. ## Public Website Cloudflare Pages Deploy The official main website deployment uses `.github/workflows/public-website-deploy.yml`. It is independent from `public-demo` and uses website-specific configuration: | Setting | Value | | --------------------------- | ---------------------------------------------- | | Pages project default | `factionos-public-website` | | Project override variable | `CLOUDFLARE_PUBLIC_WEBSITE_PAGES_PROJECT_NAME` | | Production URL default | `https://faction-os.com/` | | Smoke URL override variable | `FACTIONOS_PUBLIC_WEBSITE_URL` | | Root directory | `public-website` | | Build command | `npm run build` | | Build output directory | `dist` | The workflow expects repository or environment secrets `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` only for deploy. Missing secrets, an empty project name, or a missing Pages project produce a skipped deploy notice after the static gates pass; they do not fail local development, local build validation, or credential-free CI checks. Manual fallback from an authorized environment remains: ```bash npm ci --no-audit --no-fund npm --workspace @factionos/public-website run typecheck npm --workspace @factionos/public-website run build npm --workspace @factionos/public-website run check:links npx wrangler pages deploy public-website/dist \ --project-name="${CLOUDFLARE_PUBLIC_WEBSITE_PAGES_PROJECT_NAME:-factionos-public-website}" \ --branch="$(git branch --show-current)" \ --commit-hash="$(git rev-parse HEAD)" \ --commit-message="$(git log -1 --pretty=%s)" ``` Set `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` in the shell or CI secret store before the manual deploy. Do not place raw secret values, Cloudflare account ids, dashboard dumps, credential-bearing URLs, or deploy token output in tracked files, workflow logs, issue comments, or release notes. Post-deploy homepage smoke runs only when the deploy ran. The target must be an HTTPS URL without credentials, query strings, fragments, or localhost hosts. Log only sanitized host/status/error labels. If credentials, dashboard access, domain activation, live deploy, or hosted smoke are unavailable, record `skipped`, `blocked`, or `unavailable` evidence rather than claiming production validation. ### Public Website Launch Review Outcome Phase 16 Session 05 launch review status on 2026-06-02: | Area | Status | Evidence | | ----------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | Local website typecheck | passed | `npm --workspace @factionos/public-website run typecheck` passed under Node `26.2.0` and npm `11.16.0`. | | Local website build | passed | `npm --workspace @factionos/public-website run build` built 31 pages. | | Built-site checker | passed | `npm --workspace @factionos/public-website run check:links` passed with 31 routes and 2185 links. | | Root workspace gates | passed | Root format, lint, typecheck, build, secret scan, and whitespace checks passed. | | Local browser QA | passed | 19 critical routes were checked at 360px, 768px, 1280px, and 1600px, including nav, CTAs, focus, images, reduced motion, and overflow checks. | | Workflow readiness | passed | `.github/workflows/public-website-deploy.yml` runs website gates before credential-safe Pages deploy and bounded smoke. | | Cloudflare deploy credentials | unavailable | Local shell did not provide Cloudflare deploy credentials. | | Domain/dashboard readiness | unavailable | Cloudflare dashboard and domain status were not available in the local launch-review shell. | | Live Pages deploy | no-claim | No authorized deploy ran in the local launch-review shell. | | Production homepage smoke | no-claim | No bounded HTTPS smoke ran because no live deploy was available. | Use these status labels in future public website deploy records: `passed`, `failed`, `skipped`, `blocked`, `unavailable`, and `no-claim`. Missing credentials or dashboard access are not local source failures, but they do block production-hosted validation claims. Before claiming `https://faction-os.com/` is live-validated, an authorized operator must deploy `public-website/dist` through the workflow or Wrangler fallback, then run the bounded homepage smoke against an HTTPS target without credentials, query strings, fragments, or localhost hosts. The smoke record must keep output sanitized to host, status, retry count, and stable error codes. The website deployment must not use `public-demo/`, the `factionos-public-demo` Pages project, `CLOUDFLARE_PAGES_PROJECT_NAME`, or `FACTIONOS_PUBLIC_DEMO_URL`. The demo remains at `https://demo.faction-os.com/`, and public docs remain at `https://faction-os.gitbook.io/faction-os-docs`. ## Public Demo Media Deployment Boundary The public demo is the only deployed Phase 04 media surface documented here. It is a static artifact with synthetic data, standalone assets, and service worker cache version `factionos-demo-v9`. Current media validation covers the local static-demo server and browser offline reload after one online visit; it does not validate a production-hosted app shell, hosted accounts, analytics, or public replay hosting. Phase 05 separately validates local app browser states for optional web-to-Worker War Room federation. When `public-demo/` media, `public-demo/sw.js`, or the manifest changes, rerun `npm run media:demo:check`, `npm run media:gates:check`, and the public-demo desktop/mobile Playwright projects before deploying. Background music remains lazy-loaded and must not be added to the service-worker shell cache without a reviewed cache-budget exception. ## War Room Worker Deploy The preferred deploy path is the GitHub Actions workflow [`warroom-deploy.yml`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.github/workflows/warroom-deploy.yml). It requires repository secrets for `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID`. Cloudflare credentials are required only to deploy or operate the optional Worker surface. Core local FactionOS server and web workflows must continue to work without those credentials and without a Worker URL. ```bash cd apps/warroom wrangler login npm install npm run deploy ``` Validate after deploy: ```bash curl --fail --show-error --max-time 8 https://warroom.faction-os.com/health curl --fail --show-error --max-time 8 \ https://factionos-warroom.apex-web-services-llc-0d4.workers.dev/health npm run release:hosted-smoke -- --target warroom-worker-custom --target warroom-worker-workers-dev ``` The deploy workflow runs the same bounded health smoke check after `wrangler deploy`. Set the repository variable `CLOUDFLARE_WARROOM_HEALTH_URL` to override the default custom-domain health URL. The smoke check validates only compact health metadata and logs service, deployment type, and whether app-level rate limiting is enabled. For local Wrangler validation: ```bash npm --workspace @factionos/warroom run dev curl --fail --show-error --max-time 8 http://127.0.0.1:8790/health ``` The health response is browser-safe: ```json { "ok": true, "service": "factionos-warroom", "time": "2026-05-30T00:00:00.000Z", "rateLimit": { "enabled": true, "max": 240, "windowMs": 60000 }, "deployment": { "label": "custom-domain", "urlType": "custom-domain" } } ``` It must not include Cloudflare account ids, zone ids, tokens, request headers, client IPs, request bodies, room payloads, prompt content, command output, or local paths. The Worker has application-level rate limiting: 240 requests per 60 seconds per connecting IP. Cloudflare dashboard/API checks on 2026-05-29 showed: * The Worker custom domain `warroom.faction-os.com` is attached to `factionos-warroom`. * Managed/OWASP WAF rulesets were not entitled on the current Cloudflare account/zone plan. * The `http_ratelimit` zone phase already has its single available rule slot occupied by `Leaked credential check`. Follow `docs/runbooks/cloudflare-waf.md`. Do not replace the existing leaked-credential rule unless that tradeoff is explicitly approved. Socket validation remains separate from the health probe. A socket upgrade check requires an existing room code and approved participant id: ```bash npx wscat -c "wss://warroom.faction-os.com/rooms/ABC234/socket?participant=leader-id" ``` Expected failure states are compact Worker envelopes such as `expected_upgrade`, `missing_participant`, `pending_approval`, or `forbidden_participant`; do not paste raw participant data, request bodies, or tokens into deploy logs while debugging. Phase 05 keeps the deployment boundary explicit: the Worker backend is optional and shipped, the web panel can use it for room lifecycle, diagnostics, approval, presence, reconnect, bounded catch-up, and allowlisted redacted federation, the local server `/warroom` route is not a proxy, and local cockpit use remains available without a Worker URL. See `.spec_system/archive/phases/phase_05/war_room_requirements_trust_baseline.md` and `.spec_system/archive/phases/phase_05/war_room_payload_redaction_baseline.md`. Phase 06 Session 01 keeps the same deployment boundary. The collaboration and isolation baseline lives in `.spec_system/archive/phases/phase_06/collaboration_isolation_safety_baseline.md`. Phase 06 authority, event, UX, isolation, and mobile work must not make Cloudflare credentials, hosted accounts, hosted storage, analytics, public replay hosting, Docker, remote runners, or real executors required for local development. Phase 06 Session 07 closeout evidence is recorded in `.spec_system/archive/sessions/phase06-session07-collaboration-isolation-and-mobile-validation-closeout/`. It validates local protocol, Worker, web, server, CLI, hook, desktop, and mobile evidence for collaboration, authority, safe frames, isolation diagnostics, unsupported-route envelopes, and local browser behavior. It does not replace a deployed Worker health probe, Cloudflare dashboard review, production-hosted app validation, release-candidate smoke, mobile certification, hosted identity review, or trusted erasure design. Phase 07 hosted-service guardrails add variable and payload categories for later implementation sessions. They do not replace deployed Worker health probes, Cloudflare dashboard review, production-hosted app validation, release-candidate smoke, hosted identity review, trusted erasure design, or release hardening. Operator diagnostics for hosted readiness must report compact posture only and must not expose Cloudflare account ids, zone ids, API tokens, tunnel tokens, request bodies, room payloads, prompts, command output, local paths, exports, scans, media drafts, logs, or backups. The Session 03 hosted identity diagnostics route is a local planned-state posture endpoint, not a deployment smoke test for accounts. It must not be used as evidence of SSO, organization membership, public collaboration safety, analytics consent, production audit proof, or trusted erasure. The Session 04 hosted persistence diagnostics route is also a local planned-state posture endpoint, not a deployment smoke test for storage or public replay. It must not be used as evidence of Supabase readiness, RLS, bucket policy, hosted replay upload, public replay pages, retention, deletion, takedown, release-grade deletion, production-hosted validation, or trusted erasure. The Session 06 hosted operations diagnostics route is a local planned-state posture endpoint, not a deployment smoke test for Web Push, Cloudflare Tunnel, remote access, remote execution, hosted diagnostic agents, production-hosted validation, or trusted erasure. It must not return raw VAPID private keys, Cloudflare account ids, zone ids, API tokens, tunnel tokens, request bodies, room payloads, prompts, command output, local paths, logs, backups, exports, archives, replay buffers, scans, or media drafts. Phase 07 Session 07 closeout validated these hosted-service guardrails as local, disabled, or planned posture only. No hosted deployment surface was activated. Production-hosted validation (deployed app, deployed Worker release smoke, Cloudflare dashboard checks, production account behavior) remains blocked or no-claim unless a release record shows a safe live smoke pass; local, mocked, and same-origin evidence does not prove deployed behavior. Phase 08 Session 01 routes production-hosted validation to Session 05 in `.spec_system/archive/phases/phase_08/phase08_requirement_routing_matrix.md` and records the release risk in `.spec_system/archive/phases/phase_08/phase08_release_risk_matrix.md`. Session 05 added sanitized smoke tooling and no-network evidence, and Session 08 live smoke still blocks deployed public demo, Worker, and app-shell claims. Deploy docs must not describe local/mocked browser checks, Worker health docs, Cloudflare dashboard observations, or public demo deployment metadata as production-hosted validation. ## Rollback | Surface | Rollback path | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Cloudflare Pages demo | Revert or check out a known-good commit, then redeploy `public-demo/` to `factionos-public-demo` with Wrangler. | | Cloudflare Pages public website | Revert or check out a known-good commit, rerun `npm --workspace @factionos/public-website run typecheck`, `npm --workspace @factionos/public-website run build`, and `npm --workspace @factionos/public-website run check:links`, then redeploy `public-website/dist` to `factionos-public-website` with Wrangler. | | GitHub Pages fallback demo | Revert the commit that changed `public-demo/` and let the Pages workflow redeploy, if repository Pages is enabled. | | War Room Worker | Revert or check out a known-good commit, then run `npm --workspace @factionos/warroom run typecheck` and `npm --workspace @factionos/warroom run deploy`; verify `/health` after deploy. | | Self-hosted server/web | Restart the previous build artifact or previous git revision. | Rollback when a health check fails after deploy, event ingest fails, the web app cannot hydrate, room creation/join breaks, or privacy-sensitive data is sent to an unintended external surface. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/docs/deployment.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.