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:
- Create a fine-grained GitHub personal access token with access to
12ff54e/equilibria-collectionand Contents → Read-only permission. In the repository's Settings → Environments, openaccess_equilibira_collectionand add the token as the environment secretEQUILIBRIA_COLLECTION. Replace this secret before the token expires. - Create a Cloudflare API token with Account → Cloudflare Pages → Edit
permission for the account containing the
facsproject. - In the repository's Settings → Environments, create or open
cf. Under Environment secrets, addCLOUDFLARE_API_TOKENwith that token andCLOUDFLARE_ACCOUNT_IDwith the account ID. - Push the workflow to
main, then create and push a version tag on a commit containing this workflow. Each newv*tag builds and publishes that release. To check a build manually, open Actions → Build and deploy Cloudflare Pages → Run workflow and selectmain.
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.