AI Agent Cloudflare Deployment

This document is the deployment contract for AI agents. If a user asks an agent to deploy EdgeEver from a GitHub URL to Cloudflare, follow this runbook before asking the user for anything.

One Prompt Install

Users should be able to start with only this prompt:

This is the GitHub project URL: <repo-url>. Install and deploy this project to Cloudflare for me.

Chinese version:

这个是 GitHub 上的项目链接：<repo-url>。请把这个项目安装部署到 Cloudflare 上。

Agent Rules

Read AGENTS.md, README.md, .env.local.example, and this file first.
Do not create a new Git branch. Work on main.
Treat deployment as two required phases: use bun run deploy:setup, bun run deploy:doctor, and bun run deploy only for the initial installation; then run bun run deploy:builds:setup so all routine updates use Cloudflare Workers Builds.
Do not hard-code a personal Worker name, D1 database ID, R2 bucket name, account ID, API token, or domain in source files.
Use .env.local for local/private deployment values. It is git-ignored.
If the Cloudflare MCP or Cloudflare plugin is available, it may be used to inspect or create resources. If not, use Wrangler through the scripts in this repo.
Ask the user only for values that cannot be inferred or generated safely, such as Cloudflare authorization, the first login password, or custom domain ownership.

Required Tools

Bun
Wrangler, installed by bun install as a project dev dependency
A Cloudflare account authorized by either wrangler login or CLOUDFLARE_API_TOKEN

Standard Flow

Clone the repository and enter it.
```
git clone <repo-url>
cd edgeever
```
Install dependencies.
```
bun install
```
Ensure Cloudflare authentication.
```
bunx wrangler whoami
```
If this fails, ask the user to finish Cloudflare login or provide a suitable API token. Do not continue deployment until this works.
Prepare deployment resources and .env.local.

If the user gave a first login password, run:
```
EDGE_EVER_PASSWORD='<first-login-password>' bun run deploy:setup
```
If no password was provided, ask for one or ask permission to generate a random password. Then rerun the command with EDGE_EVER_PASSWORD.

deploy:setup will:
- copy .env.local.example to .env.local when needed
- reuse or create the D1 database
- create the R2 buckets when needed
- generate EDGE_EVER_AUTH_PASSWORD_HASH from EDGE_EVER_PASSWORD
Check the deployment inputs.
```
bun run deploy:doctor
```
Fix every fail result before deploying.
Deploy.
```
bun run deploy
```
bun run deploy builds the web app, applies remote D1 migrations, and deploys the Worker. During deploy, scripts/run-wrangler.mjs uploads EDGE_EVER_AUTH_PASSWORD_HASH as a Worker Secret via a generated .env.wrangler.generated*.secrets file, then synchronizes it again with wrangler secret put after a successful deployment so the first login does not depend on the bulk secrets upload alone.
Verify the result.

Use the Worker URL from Wrangler output, then check:
```
curl -I https://<worker-url>/
curl https://<worker-url>/api/openapi.json
```
Open the site, log in with EDGE_EVER_AUTH_USERNAME and the first login password, then create an MCP token from the in-app MCP settings.
Connect Cloudflare Workers Builds.

Prefer the automated setup command:
```
bun run deploy:builds:setup
```
It reads the fork remote and .env.local, then creates or updates the Cloudflare repository connection, production trigger, build commands, cache, watch paths, and build variables. The configuration API requires a User API Token (My Profile -> API Tokens), not an Account API Token; it must have Workers Builds Configuration: Edit and Workers Scripts: Read, and be set as EDGE_EVER_BUILDS_API_TOKEN. The agent should complete the Cloudflare GitHub App authorization in the browser when available. If Cloudflare requires a build-token choice, use the exact Dashboard path and retry command shown in Cloudflare Workers Builds.

Once connected, a GitHub Sync fork push automatically migrates and deploys the user's own instance. Do not configure the repository's GitHub Actions Worker deployment for this purpose.

Optional Customization

Set these values in .env.local before bun run deploy:setup or bun run deploy:

EDGE_EVER_WORKER_NAME=edgeever
EDGE_EVER_D1_DATABASE_NAME=edgeever
EDGE_EVER_R2_BUCKET_NAME=edgeever-resources
EDGE_EVER_R2_PREVIEW_BUCKET_NAME=edgeever-resources-preview
EDGE_EVER_AUTH_USERNAME=admin
EDGE_EVER_SESSION_TTL_DAYS=400
EDGE_EVER_CUSTOM_DOMAIN=notes.example.com

For multiple instances, set EDGE_EVER_INSTANCE=<name> and use scoped variables such as:

EDGE_EVER_PROD_WORKER_NAME=edgeever-prod
EDGE_EVER_PROD_D1_DATABASE_ID=<database-id>
EDGE_EVER_PROD_R2_BUCKET_NAME=edgeever-prod-resources
EDGE_EVER_PROD_AUTH_PASSWORD_HASH=<password-hash>

Blocking Conditions

Stop and ask the user only when:

Cloudflare authentication is missing and the agent cannot open or complete login.
The user must choose or provide the first login password.
The requested custom domain is not available in the Cloudflare account.
Resource creation fails because of account limits, permissions, billing, or conflicting names that cannot be resolved by choosing a new name.

Final User Response

After deployment, report:

deployed URL
login username
whether the password was user-provided or generated
where to create the EdgeEver MCP token in the app
confirmation that Workers Builds is connected and that future main pushes automatically migrate and deploy
any custom domain or Cloudflare DNS step that remains

5.8 KiB Raw Blame History