Deploy to Cloudflare Pages

Use ./build_web.sh --cloudflare for publication. This build removes the private repository links from the app. The default local build keeps them. Install the documentation tools first with python3 -m pip install -r requirements-docs.txt. The Cloudflare build compiles the root README and solver documentation into build/pages/docs/, which the app's Documentation link opens. The pages include navigation, search, equations, and algorithm diagrams. Local source references appear as text in the published pages. The theme button shares the solver's saved light or dark preference. To rebuild only the documentation, run python3 script/build_docs.py.

./build_web.sh also creates build/pages/ with index.html, index.js, index.wasm, the page assets, formats_worker.mjs, export_data.mjs, facs_formats.mjs, facs_formats.wasm, the equilibria/ catalog and files, and third-party license notices. The Cloudflare build also includes docs/. Upload build/pages/ with its _headers file. It excludes CMake files, tests, and stale runtime files. The header rules enable shared memory on all static paths; keep them in the upload directory. See Cloudflare's _headers documentation.

Manual upload

cf pages list inspects the existing facs project. Its production branch is cf-page. The tested cf version, 1.0.0-beta.17, refuses directory uploads to existing Pages projects. Use Wrangler for the upload:

npx wrangler@4.151.0 login
npx wrangler@4.151.0 pages deploy build/pages --project-name=facs --branch=web-preview

The explicit preview branch keeps the test separate from facs.pages.dev. Wrangler can upload to the existing Git-integrated project without changing its Git settings. To publish to production, use --branch=cf-page instead. See Cloudflare's direct upload guide.

GitHub Actions

The GitHub Actions workflow publishes when you push a new version tag matching v*, such as v1.1.1. It builds the tagged commit. Pull requests targeting main and manual runs build without deploying. Each workflow build replaces the bundled catalog with the tracked files from the main branch of 12ff54e/equilibria-collection. Update that repository's index.json and g-files before the next build to change the deployed selection. Local builds use web/equilibria/. GitHub's workflow token checks out the private repository and its submodules; Cloudflare receives the prebuilt site through its API. The workflow pins the tested Emscripten 6.0.9 and Wrangler 4.151.0 versions. It uses --branch=cf-page to update facs.pages.dev and checks that the upload targets production. The build job uses the access_equilibira_collection environment to read the collection and saves the site as an artifact. The deployment job uses the cf environment and its secrets.

Credentials and releases

To enable deployment:

  1. Create a fine-grained GitHub personal access token with access to 12ff54e/equilibria-collection and Contents → Read-only permission. In the repository's Settings → Environments, open access_equilibira_collection and add the token as the environment secret EQUILIBRIA_COLLECTION. Replace this secret before the token expires.
  2. Create a Cloudflare API token with Account → Cloudflare Pages → Edit permission for the account containing the facs project.
  3. In the repository's Settings → Environments, create or open cf. Under Environment secrets, add CLOUDFLARE_API_TOKEN with that token and CLOUDFLARE_ACCOUNT_ID with the account ID.
  4. Push the workflow to main, then create and push a version tag on a commit containing this workflow. Each new v* tag builds and publishes that release. To check a build manually, open Actions → Build and deploy Cloudflare Pages → Run workflow and select main.

Pull requests and manual runs build without using the deployment credentials. The workflow fails with a clear error if either secret is missing. Production runs finish before another starts, including runs for different version tags; new commits can cancel an older pull-request build. See Cloudflare's CI guide.