OpenFlare/docs/en/guide/pages-usage.md

Pages Static Hosting Usage

You will learn: how to deploy pre-built static sites via local upload, Remote URL, or public GitHub Release assets; configure SPA Fallback and API reverse proxy; and safely check for updates, auto-publish, and roll back.

---

Core Mechanics and Page Structure

OpenFlare Pages is inspired by Cloudflare Pages' Direct Upload and deployment history interaction, but currently handles pre-built artifacts rather than building from repository source. The project detail is organized as "current production deployment → deployment source → deployment history": source configuration can change, while created deployments stay immutable.

Local upload ─> unified validation / upload.Ingest ─> new candidate ─> admin explicit activation ─┐
Remote URL ── Server restricted download ─────────────┐                                            │
GitHub Release asset ─ Server resolves ───────────────┴─> create/load deployment ────────────────┤
                                                       └─> source sync atomic activation ────────┘
                                                                                                   |
                                                                                                   v
                                                                        Agent pulls per-project latest
                                                                                                   |
                                                                                                   v
                                                                        OpenResty local static serving

External URLs, GitHub metadata, and auto-checks are handled only by the Server. The Agent only pulls the currently active deployment package from the control plane; it does not receive external source credentials, nor does it run git clone, dependency installation, or build commands.

Step 1: Create a Project

1. Log in to the admin panel, go to 「Pages」, click 「Create Project」.
2. Fill in the project name and a unique Slug.
3. Configure the content entry:
   • Entry file name: default index.html.
   • Static asset root path (RootDir): fill in the relative path when artifacts are in a subdirectory like dist/; leave empty when artifacts are at the archive root.
4. Set SPA Fallback and API proxy as needed. RootDir and entry file are project-level configs applied uniformly to all sources.

Step 2: Choose a Deployment Source

1. Manual Upload

Without a persistent source configured, the project stays in manual mode. Click 「Upload Deployment Package」 to select a pre-built archive; a successful upload creates a candidate deployment, which you then explicitly activate from the deployment history. Re-uploading does not modify existing deployments.

Supported formats: zip, tar.gz / tgz, tar.xz / txz, tar.bz2 / tbz2, tar, and 7z.

2. Remote URL

In the deployment source card select Remote URL, fill in the HTTP(S) address and choose a network policy:

• public: default policy; rejects loopback, private network, link-local addresses, DNS rebinding, self-signed TLS, and redirects to non-public targets.
• trusted_internal: only for explicitly trusted intranet or self-signed services; requires a second risk confirmation before saving.

After saving, the address is only displayed masked. You don't need to re-enter it when editing other configs; only submit a new URL when choosing to change the address. Remote sources only offer 「Sync and Publish」: the Server downloads, validates, and atomically activates each time — no "check for updates", scheduled checks, or auto-updates.

3. GitHub Release

GitHub sources only support public github.com repositories. Fill in:

• A repository address in https://github.com/{owner}/{repo} format;
• Latest Release or a fixed Tag;
• An exact, case-sensitive Release Asset filename, default dist.zip.

Both options support manual 「Check for Updates」 and 「Sync and Publish」. Differences:

• latest: supports a check interval of 5–1440 minutes, default 1440 minutes (24 hours); auto-update is off by default. When enabled, the scanner asynchronously syncs and publishes only when a new revision is found.
• tag: only supports manual admin checks and sync; does not participate in the scheduled scanner.

"Check for updates" only resolves the Release/asset and advances the version cursor without downloading the deployment package; "Sync and publish" downloads, validates, creates or reuses a deployment, and activates it. If the asset under the same Release is replaced, the source enters 「Needs Confirmation」 — you must confirm the exact revision shown before publishing, to avoid silent overwrites.

GitHub Release sources only import pre-built artifacts; they do not build from repository source.

4. Switch or Delete a Source

You can switch between Manual, Remote, and GitHub Release. Modifying or deleting a source does not delete the current production deployment or historical deployments; switching back to manual mode lets you continue uploading and explicitly activating.

Deployment Package Security Limits

Deployment packages must satisfy these constraints:

• Archive size is controlled by the system config pages_max_package_size_mb, default 100 MiB, configurable 1–2048 MiB.
• Expanded single-file and total size limits are "package size limit × 4", with a floor of 100 MiB; at most 1,000 regular files.
• The control plane streams regular file bodies, checking declared size against actual bytes, and validates the project entry file.
• Absolute paths, .. path traversal, symlinks, hard links, and special files in archives are all rejected.

The Agent also verifies SHA-256, real response byte limits, and post-extraction file count and total size on download; failures do not switch the existing current.

Step 3: Configure Advanced Routing Rules

1. SPA Fallback

When using front-end routing like React Router or Vue Router, enable 「SPA Fallback」 and set the entry path (usually /index.html). When a visitor accesses a physical path that doesn't exist, OpenResty falls back to the entry file for the front-end router to handle.

2. API Reverse Proxy

Pages can forward a specified prefix to a backend API under the same domain:

• APIProxyPath: match prefix, e.g. /api.
• APIProxyPass: backend address, e.g. http://10.0.0.5:8080.
• APIProxyRewrite: optional path rewrite rule.

Requests matching the API prefix go through the reverse proxy; other requests continue to be served by the static site.

Step 4: Bind a Route and First Publish

1. Create or edit a proxy rule.
2. Set the origin type to Pages and select the Pages project.
3. Preview the config, then publish and activate.

The route binds to a stable project ID, not a specific deployment. The first publish gives the Agent the project anchor; afterwards, local uploads, source syncs, auto-updates, or manual rollbacks only change the project's active deployment — the Agent converges via the latest hash reconciliation without needing to republish the main config.

Operations, Status, and Rollback

• The source card shows the last check/sync time, found vs. applied revision, next check time, and security errors. While a check or sync task runs, the page polls the task status; when latest is idle, it refreshes at low frequency only near the check time.
• A failed auto-update does not replace the old active deployment; a single source failure does not block the scanner from processing other projects.
• Activating another deployment in the history is a manual rollback. The system fences in-flight source tasks and disables that source's auto-update to avoid the next latest round overwriting your manual choice; re-activating the current version is a no-op.
• The Agent downloads to a temp file, verifies SHA-256, extracts safely, then atomically switches current. Any failure keeps the old content; with multi-project reconciliation, a single project failure does not affect others.

Tip

For the source state machine, auto scanner, upload compensation, immutable deployments, and Agent atomic switching, see Pages Static Hosting Design.