Pages overview
Pages publishes static sites as Projects with immutable Deployments and mutable Tags. A Deployment is a fixed artifact produced by a manual upload or a Git build. A Tag is a movable named pointer to one Deployment. Routes target Tags, never raw Deployments, which makes promotion and rollback deliberate operational actions instead of changes to an already published artifact.
For a product or engineering lead, the outcome is a controlled release path for documentation, landing pages, dashboards, and other static frontends without adding an application server. The project owner decides what is built, a release owner decides which immutable artifact a Tag selects, and the Ingress owner controls the Domain and TLS Route. Success means a release can be previewed, promoted, verified, and rolled back without rebuilding or editing the previous artifact.
Pages is appropriate for browser-delivered static output. It is not a general server runtime: API processes, background workers, stateful sessions, and server-side application code belong on workloads behind Opfield Routes.
This documentation portal and the Opfield product landing are themselves published through Opfield Pages. They use the same immutable Deployment, Tag, Route, TLS, and rollback model described here.
Resource model and ownership
Section titled “Resource model and ownership”A Pages Project owns its deployment history, Tags, Routes, runtime configuration, access relationships, and retention behavior. Opfield stores each published artifact centrally and materializes it on the assigned nginx nodes. Nginx serves the applied Pages configuration, while Opfield remains the source of truth for which Tag a Route should use.
Deployments are immutable: changing site files, build output, or source input creates a new Deployment. Tags are mutable: moving a Tag changes which already-created Deployment it selects. The system-managed latest Tag tracks the appropriate current deployment; use custom Tags for named environments, release channels, or an explicit promotion gate.
Decisions before the first release
Section titled “Decisions before the first release”Agree on five points before connecting a public Domain:
- Ownership: who may create Deployments, move production Tags, edit runtime configuration, and delete rollback candidates.
- Release source: manual artifact upload or an approved Git integration and Build Worker.
- Promotion policy: automatic deployment for low-risk sites or an explicit review before the production Tag moves.
- Retention: how many known-good Deployments must remain available and for how long.
- Runtime contract: which public values may change independently of the artifact and which changes require a new build.
Use separate Tags when environments need independent promotion. Do not use Tag names as access control: permissions and Routes remain the security boundary.
Publish from Git or manually
Section titled “Publish from Git or manually”For a Git-backed release, a supported source integration and Build Worker produce a new immutable Deployment. For a manual release, provide the ready static-site artifact and create a new Deployment from it. In either path, review the resulting artifact and deployment identity before moving a public Tag.
A manual upload can be a single HTML file, which becomes the site’s index.html, or a .tar.gz archive with index.html at its root. Finalizing the upload returns the Deployment’s preview link and, when the upload named a Tag, the Tag’s link, so an agent that generated a report can hand the user a URL right away (see the publishing-html-pages skill in AI agent skills). An upload may set an expiry (expiresInHours or expiresAt). When it passes, Opfield deletes the Deployment with its files and previews and clears the Tags that still select it; a Deployment that a Route still serves keeps its files, but its previews stop. Deploy tokens restricted to certain Tags cannot set an expiry.
Every upload—from the Console, through the resumable deploy API, or through an MCP one-time link—may be as large as the File upload limit in Settings > General > Access and limits: 100 MB by default and at most 500 MB. A larger artifact is refused with 413 PAGES_ARTIFACT_TOO_LARGE, and the project’s storage quota applies as well. An unfinished upload can be cancelled at once from the Console, the REST API, or MCP; a failed Console upload cleans up after itself, and an abandoned upload expires 30 minutes after its last chunk. Agents publish through one-time upload links with ready curl commands instead of base64 in tool calls.
Creating a Deployment does not publish it to a custom domain. Publication starts when a Route targets a Tag that points to that Deployment. This allows a team to verify a release before promotion and lets an incident rollback move a Tag without rewriting the prior artifact.
Routes, previews, and runtime configuration
Section titled “Routes, previews, and runtime configuration”Custom Routes target Tags only. Verify the Domain, TLS certificate, nginx placement, and Tag target before announcing a release. Optional wildcard previews give every Deployment an immutable hostname, useful for reviewing a particular artifact without changing a public Tag, and every Tag a stable hostname <project hash>-<tag>.<wildcard domain> that follows the Tag when it moves. The project hash is random, so preview hostnames never reveal project names. New Tag names must be lowercase DNS labels of at most 50 characters.
Previews are public to anyone who has the link. To protect them, choose an access list in the project’s Preview links settings: its IP rules and basic auth then apply to every preview of the project, and plain HTTP redirects to HTTPS. Protected previews need the nginx daemon of 2.11: a node whose daemon cannot apply access lists to previews withholds the project’s previews instead of serving them open. Disabling a project revokes its previews. Rotate links gives the project a new hash and new Deployment hostnames, which revokes every preview link it has shared so far.
Runtime configuration is public client-side data and is separate from the immutable artifact identity. It is exposed to the site as window.runtime.config, with a Default object and whole-object Tag overrides. Immutable Deployment previews use Default; a Tag Route and the Tag’s preview hostname use the Tag’s override when present or fall back to Default. Do not place secrets, credentials, or private topology in runtime configuration.
Runtime configuration is useful for public API origins, feature presentation, analytics identifiers, or environment labels that legitimately belong in the browser. A Tag override replaces the whole object rather than merging individual keys, so review every required field when creating an override. Keep the contract backward-compatible with every Deployment that the Tag may select during rollback.
Promote, roll back, and verify
Section titled “Promote, roll back, and verify”- Create a new immutable Deployment through Git or manual publishing.
- Review its build or upload result and test the artifact through an appropriate preview or controlled route.
- Move the intended Tag to the verified Deployment.
- Verify the Route’s DNS and TLS path, the expected response, static assets, and browser-visible runtime configuration.
- Monitor the Route, nginx application state, and project operations after promotion.
To roll back, move the Route’s Tag to a previous known-good Deployment. The older artifact remains unchanged, and the rollback is recorded as a Tag publication change. Keep runtime configuration backward-compatible while a Tag can move between releases; changing runtime configuration does not create a new Deployment.
The release is successful only when the custom Domain returns the intended document, referenced assets load without errors, TLS is valid, client-side navigation works after a direct refresh, and the browser receives the intended runtime configuration. An immutable preview proves the artifact; it does not prove the production Domain, certificate, Tag, or environment-specific runtime values.
Lifecycle consequences
Section titled “Lifecycle consequences”Deleting a Deployment removes that immutable release from future selection and can eliminate a rollback target. Remove it only after retention requirements and Tag references have been reviewed. Deleting a Tag or Route changes reachability, not the contents of the selected Deployment. Disabling Pages removes the feature from normal navigation while preserving project data, and Pages can be turned on again later. Deployments whose files retention has already removed are hidden from the Deployment list.
Operator details: placement and recovery
Section titled “Operator details: placement and recovery”Opfield stores the Pages artifact centrally and materializes replicas on assigned nginx Nodes. If a Route fails while the Deployment remains ready, inspect the Domain placement, Ingress Node, certificate relationship, Tag target, and Pages operation before rebuilding. Rebuilding the same source is not a substitute for restoring the serving path.
If promotion causes an incident, first move the production Tag to the previous verified Deployment. Change runtime configuration only when it is part of the failure and remains compatible with the rollback target. Preserve the failed Deployment, build record, and logs until the incident is understood; immutability makes them useful evidence.