> 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/public-website/docs/archive-docs_public-website/deployment.md).

# Public Website Deployment

The public website deploy target is Cloudflare Pages static output from `public-website/dist`.

## Deployment Boundary

The main website deploy is separate from:

* `public-demo/`
* the `factionos-public-demo` Pages project
* `https://demo.faction-os.com/`
* the public GitBook docs site
* runtime app hosts for `apps/web` or `apps/server`

The first release does not use `@astrojs/cloudflare`; static output is enough.

## Cloudflare Pages Settings

| 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`                                         |

## GitHub Actions Workflow

Workflow:

```
.github/workflows/public-website-deploy.yml
```

Triggers:

* push to `main` when public website, workflow, package, lockfile, or checker files change
* manual `workflow_dispatch`

Workflow stages:

1. Checkout.
2. Setup Node from `.nvmrc`.
3. `npm ci --no-audit --no-fund`.
4. Website typecheck.
5. Website build.
6. Built-site checker.
7. Check Cloudflare credential availability.
8. Deploy with Wrangler if credentials and project name are available.
9. Run bounded HTTPS homepage smoke if deploy ran.

## Required Deploy Secrets

Deploy-only secrets:

* `CLOUDFLARE_ACCOUNT_ID`
* `CLOUDFLARE_API_TOKEN`

Optional variables:

* `CLOUDFLARE_PUBLIC_WEBSITE_PAGES_PROJECT_NAME`
* `FACTIONOS_PUBLIC_WEBSITE_URL`

Missing deploy credentials, empty project name, or missing Pages project produce a skip notice after static gates pass. This is not a local source failure and must not expose secret values.

## Manual Deploy Fallback

Run from an authorized environment:

```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 authorized shell or CI secret store. Do not write raw secret values, Cloudflare account ids, dashboard dumps, credential-bearing URLs, or deploy token output to tracked files.

## Smoke Target Rules

The homepage smoke target must:

* use HTTPS
* have no username/password
* have no query string
* have no fragment
* not be localhost, `127.0.0.1`, `0.0.0.0`, or `::1`

The smoke check validates:

* HTTP success
* HTML body marker
* `FactionOS` content marker

Smoke output should log only sanitized host, status, retry count, and stable error code.

## Claim Rules

| Evidence                           | What it supports                              | What it does not support                         |
| ---------------------------------- | --------------------------------------------- | ------------------------------------------------ |
| Local typecheck/build/checker pass | Local static launch readiness.                | Live production deploy or HTTPS health.          |
| Workflow file exists               | Deploy path readiness.                        | A successful deploy.                             |
| Credential-skip workflow notice    | Static gates can pass without deploy secrets. | Live deployment.                                 |
| Authorized Pages deploy pass       | Cloudflare upload/deploy attempt succeeded.   | Long-term uptime, legal approval, certification. |
| Bounded HTTPS homepage smoke pass  | Sanitized homepage smoke passed after deploy. | Full site certification or runtime app health.   |

Do not claim `https://faction-os.com/` is production validated until an authorized deploy and bounded HTTPS homepage smoke pass.

## Status Labels

Use these labels in deployment records:

* `passed`
* `failed`
* `skipped`
* `blocked`
* `unavailable`
* `no-claim`

Missing credentials or dashboard access are `unavailable` or `blocked`, not a local website source failure. A live deploy that was not attempted is `no-claim`.

## Rollback

Rollback is a Cloudflare Pages operation. Use an authorized environment or the Cloudflare dashboard to restore a previous Pages deployment.

Document only sanitized rollback evidence:

* deployment id or label if safe to record
* branch
* commit hash
* status
* smoke result
* stable error code if failed

Do not commit dashboard dumps, account ids, tokens, credential-bearing URLs, or raw response bodies.

## When To Revisit The Deployment Architecture

Re-evaluate deployment if the site adds:

* server actions
* forms
* sessions
* runtime personalization
* auth
* CMS preview
* search service
* Cloudflare bindings
* analytics collection
* hosted identity or hosted storage

Those changes may require a Cloudflare Workers/adapter decision, privacy review, and new validation docs.


---

# 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/public-website/docs/archive-docs_public-website/deployment.md?ask=<question>&goal=<endgoal>
```

`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.