# 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. **Create Cloudflare Resources**
   - Create a D1 database named exactly `edgeever`.
   - Create an R2 bucket named exactly `edgeever-resources`.

3. **Create the Worker**
   - In **Workers & Pages** → **Create application** → **Start with Hello World!**, create and deploy a Worker named exactly `edgeever`.
   - This is a placeholder service, not a completed EdgeEver deployment. For an existing EdgeEver instance, reuse its Worker and authentication Secret; do not replace its application with Hello World or reset its password.

4. **Configure the Runtime Secret Before Connecting the Fork**
   - Under the Worker's **Settings** → **Variables and Secrets**, add `EDGE_EVER_AUTH_PASSWORD` as type **Secret**, using the initial administrator login password (preferably at least 32 characters), and select **Deploy**.
   - Confirm the Secret name appears in the list before connecting the repository. Keep the password only as a Worker runtime Secret, never in Workers Builds variables or Fork files.

5. **Connect the Fork**
   - Open this existing Worker's **Settings** → **Builds** → **Connect**, authorize GitHub access, and select the Fork's `main` branch. Follow [Cloudflare's existing-Worker instructions](https://developers.cloudflare.com/workers/ci-cd/builds/#connect-an-existing-worker). Do not use the Deploy to Cloudflare template entrypoint or create a Pages application.
   - Use the repository root and default deploy command `npx wrangler deploy`; Cloudflare runs it online through EdgeEver's validated deployment pipeline. Existing deployments may keep explicit `bun run build:cloudflare` and `bun run deploy:cloudflare-builds` commands.
   - Do not edit `wrangler.toml` or add duplicate bindings. Deployment automatically resolves the D1 UUID from `edgeever` and generates temporary `DB` and `RESOURCES` bindings. For a different database name, set `EDGE_EVER_D1_DATABASE_NAME`; use `EDGE_EVER_D1_DATABASE_ID` only if UUID discovery is unavailable. Non-secret instance settings belong in Workers Builds variables.
   - Existing deployments retain their live `RESOURCES` binding and administrator username unless explicitly overridden; do not ask users to rename or reconfigure a custom R2 bucket. Keep tracked configuration unchanged so the Fork remains a deployment mirror.

6. **Configure Deployment Permissions**
   - In **Settings → Builds → API token**, select or create the Cloudflare API token used by Workers Builds to deploy the application. **Create new token** generates a token automatically; its defaults may lack D1. Add D1 read/edit permission for the target account under [My Profile → API Tokens](https://dash.cloudflare.com/profile/api-tokens), retaining its existing deployment permissions. Select this token in the Worker’s **Settings → Builds → API token** and save the build settings. Subsequent Cloudflare Workers Builds runs use it for database migrations and Worker deployment.

7. **Start the First Build and Verify the Service**
   - Use `admin` unless the user requests another username; configure `EDGE_EVER_AUTH_USERNAME` before starting the first build if requested.
   - In the Fork's GitHub repository, open **Actions → Update deployed EdgeEver**, enable the workflow if prompted, select `main`, and click **Run workflow**. This republishes the selected upstream version even when the Fork is already aligned. Return to Cloudflare **Deployments** to monitor the corresponding build.
   - Missing authentication configuration is a deployment error to correct, not an expected first-build failure. Keep all authentication and deployment checks enabled.
   - After confirming in Cloudflare that the corresponding build succeeded and deployment completed, verify `/api/health` returns HTTP `200` with `{"ok": true}`, `/api/openapi.json` is reachable with JSON containing `"ok": true`, and the login API accepts the configured administrator username and password. A Hello World response does not pass verification.

   - This workflow will automatically sync future stable releases and fixes.

## Upstream Update Channel
   - 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.
   - 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**.

## Optional: Customize the Initial Administrator Username

Ordinary deployments use the default username `admin`; do not proactively ask the user whether to change it. Only when the user explicitly requests a custom administrator username, set `EDGE_EVER_AUTH_USERNAME` in Workers Builds variables before starting the first build and use that username during login verification. Changing only this variable after the administrator account exists does not rename that account.