edgeever/docs/agent-deploy-cloudflare.md

AI Agent Cloudflare Deployment Guide

This document defines the standard operating specifications and conventions for AI Agents (and automated deployment scripts) deploying EdgeEver on Cloudflare.

💡 Core Principle: Pure Serverless architecture running entirely within Cloudflare free limits—no VPS or server purchasing, no Docker or SSL certificate configuration required.

---

Standard Automated Deployment Steps

1. Fork Repository

   • Fork tianma-if/edgeever to the target GitHub account.

2. Enable Workflow

   • In the Actions tab of the Forked repository, enable the Update deployed EdgeEver automatic update workflow (required on public forks: scheduled workflows are disabled by default).
   • An ordinary Fork is a deployment mirror by default. No update variable is required: the workflow applies the selected upstream Release's product snapshot to main before triggering Cloudflare.
   • The updater preserves the Fork's complete .github/workflows/** directory and its two updater helper scripts as a stable local bootstrap layer. Official packaging, signing, testing, and Release workflows remain guarded to tianma-if/edgeever and are never rewritten by downstream product updates.
   • Only a Fork that intentionally maintains application-code changes should create the Actions repository variable EDGE_EVER_PRESERVE_FORK_CHANGES=true. This opts into merges and requires the owner to resolve future conflicts; it is not needed for normal deployments.

3. Cloudflare Project Import

   • Log into the Cloudflare Workers & Pages console and import the Fork repository.
   • Configure the project to use the repository root, the production main branch, and read the root wrangler.toml.

4. Resources & Secrets

   • Create a D1 database named exactly edgeever.
   • Create an R2 bucket named exactly edgeever-resources.
   • Worker Secret: Add secret EDGE_EVER_AUTH_PASSWORD for initial admin password.
   • Keep this password only as a Worker runtime Secret; do not copy it into Workers Builds variables. The standard deploy entrypoint reuses and verifies the existing Secret.
   • Do not edit wrangler.toml or add duplicate bindings in the Dashboard. The deployment command generates the DB and RESOURCES bindings from these standard resource names.

5. Configure Workers Builds Commands

   • In the Cloudflare project build settings, set the standard commands:

     Build command: bun install --frozen-lockfile && EDGE_EVER_DEPLOYMENT_TRIGGER=main_push EDGE_EVER_DEPLOYMENT_METHOD=cloudflare_workers_builds bun run build:cloudflare
     Deploy command: bun run deploy:cloudflare-builds
     

   • The deploy command automatically resolves the D1 UUID from the edgeever database name and writes all instance settings only to a temporary generated Wrangler configuration. The tracked wrangler.toml must remain unchanged; deployment rejects instance-specific values committed there so a Fork cannot diverge on infrastructure configuration.

   • Ensure the Workers Builds API token can read and edit D1. Advanced non-secret customization belongs in EDGE_EVER_* Workers Builds variables. For a differently named database, set EDGE_EVER_D1_DATABASE_NAME; set EDGE_EVER_D1_DATABASE_ID only if automatic UUID discovery is unavailable. Passwords remain runtime Secrets.

6. Start Initial Build & Verify Service

   • Trigger the initial build. Once deployed, run the following automated verifications:
     • Check https://<your-worker-domain>/api/health returns HTTP 200 with JSON {"ok": true}.
     • Check https://<your-worker-domain>/api/openapi.json loads the OpenAPI schema properly.
     • Verify login API using username admin and EDGE_EVER_AUTH_PASSWORD. If an advanced deployment sets the EDGE_EVER_AUTH_USERNAME Builds variable, use that username instead.

7. Verify Upstream Update Channel

   • Manually trigger Update deployed EdgeEver once in the Fork's Actions tab.
   • Open the job Summary and confirm it reports Fork mode mirror, the upstream target (stable Release or edge main), and either an update publish or an explicit already aligned result.
   • Confirm Cloudflare Deployments builds the published main commit when a push occurred.
   • Do not edit deployment files or rely on GitHub Sync fork for routine upgrades; the workflow is the only synchronization path needed by a normal deployment Fork. Use Sync fork once only when an old Fork must receive a newer updater workflow itself, then return to Update deployed EdgeEver.