Files
Sable/infra/README.md
2026-07-26 14:51:16 -05:00

115 lines
4.3 KiB
Markdown

# Infrastructure
`infra/web` manages the Cloudflare Worker, immutable Worker versions, the live
production deployment, and the production custom domain.
Prerequisites:
- OpenTofu `1.11.x` installed locally
- Node.js/pnpm installed locally so you can build `dist/` before Worker uploads
- A Cloudflare account with the target zone already onboarded to Cloudflare
- A GitLab project to store the OpenTofu state
- A GitLab access token that can read and write that project's OpenTofu state
Required GitHub repository secrets:
- `TF_CLOUDFLARE_API_TOKEN`
- `TF_VAR_ACCOUNT_ID`
- `TF_VAR_ZONE_ID`
- `TF_HTTP_USERNAME`
- `TF_HTTP_PASSWORD`
Required variables in both the `development` and `production` GitHub Environments:
- `SENTRY_ORG`
- `SENTRY_PROJECT`
- `TF_HTTP_ADDRESS`
- `TF_HTTP_LOCK_ADDRESS`
- `TF_HTTP_UNLOCK_ADDRESS`
- `TF_VAR_CUSTOM_DOMAIN`
- `TF_VAR_WORKER_NAME`
The HTTP backend addresses must point to distinct OpenTofu states for development
and production.
The workflows map those secrets and variables onto the runtime environment variable
names that Cloudflare and OpenTofu expect.
Cloudflare API token permissions:
- `Account > Workers Scripts > Edit`
- Scope the token to the specific Cloudflare account that owns the Worker.
- Scope the token to the specific zone that serves `app.sable.moe`.
- Do not grant Pages or DNS edit permissions here. The Worker script upload and
custom-domain attach endpoints used by this repo accept Workers Scripts Write, and
Cloudflare creates the DNS record for the Worker custom domain automatically.
GitLab access token permissions:
- `api`
Helpful reference links:
- Create the main Cloudflare API token:
https://developers.cloudflare.com/fundamentals/api/get-started/create-token/
- Find your account ID and zone ID:
https://developers.cloudflare.com/fundamentals/account/find-account-and-zone-ids/
- GitLab-managed OpenTofu state:
https://docs.gitlab.com/user/infrastructure/iac/terraform_state/
Local setup:
1. Copy `terraform.tfvars.example` to `terraform.tfvars` and fill in shared values.
2. Copy `gitlab.http.tfbackend.example` to `gitlab.http.tfbackend` and fill in the
GitLab project ID, state name, and username.
3. Run `pnpm install` from the repo root.
4. Export the GitLab access token as the backend password.
5. Export the Cloudflare API token for OpenTofu.
6. Run `pnpm run build` before `tofu plan` or `tofu apply`, because
`cloudflare_worker_version` uploads the built `dist/` assets.
7. Initialize the backend.
Local OpenTofu production flow from the repo root:
```bash
pnpm run build
export TF_HTTP_PASSWORD="<your-gitlab-access-token>"
export CLOUDFLARE_API_TOKEN="<your-cloudflare-api-token>"
tofu -chdir=infra/web init -reconfigure -backend-config="../gitlab.http.tfbackend"
tofu -chdir=infra/web validate
tofu -chdir=infra/web plan -var-file="../terraform.tfvars"
tofu -chdir=infra/web apply -var-file="../terraform.tfvars"
```
Optional local OpenTofu deployment message:
```bash
export TF_VAR_workers_message="$(git log -1 --pretty=%s)"
tofu -chdir=infra/web apply -var-file="../terraform.tfvars"
```
If you already created local state before switching to GitLab state, use
`tofu -chdir=infra/web init -reconfigure -migrate-state -backend-config="../gitlab.http.tfbackend"`
once instead.
Preview builds:
- `infra/web/main.tf` enables preview URL capability with `subdomain.previews_enabled = true`.
- Previews are handled by Cloudflare Workers Builds, not GitHub Actions.
- Connect the repo once in Cloudflare Workers Builds.
- Set the Cloudflare Builds deploy command to `npx wrangler versions upload`.
- This disables automatic deployments while still allowing Cloudflare to build PRs/branches and save them as preview versions.
- That keeps Cloudflare from promoting `dev` commits to production. Production stays on the OpenTofu/GitHub Actions path in this repo.
```bash
npx wrangler versions upload
```
Production deploys:
- `.github/workflows/cloudflare-web.yml` comments PR plans for `infra/web` changes.
- That PR plan job only runs for same-repo PRs, not fork PRs, because it needs repo secrets.
- The workflow applies dev on pushes to `dev` or manual dispatch without tag; production on pushes to tags or manual dispatch with a tag.
- `tofu apply` uploads `dist/` through `cloudflare_worker_version` and promotes it with `cloudflare_workers_deployment`.
- Production lives on `app.sable.moe`.