This repository has been archived on 2026-10-25. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files

105 lines
4.0 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_ADDRESS`
- `TF_HTTP_LOCK_ADDRESS`
- `TF_HTTP_UNLOCK_ADDRESS`
- `TF_HTTP_USERNAME`
- `TF_HTTP_PASSWORD`
The workflows map those secrets onto the actual 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-deploy.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 same workflow applies production on pushes to `dev` or manual dispatch.
- `tofu apply` uploads `dist/` through `cloudflare_worker_version` and promotes it with `cloudflare_workers_deployment`.
- Production lives on `app.sable.moe`.