Skip to content

AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.

docs: streamline Cloudflare agent runbook

yomaeabcdda651cd
diff --git a/docs/agent-deploy-cloudflare.md b/docs/agent-deploy-cloudflare.md
index f976e562..3d86ffb7 100644
--- a/docs/agent-deploy-cloudflare.md
+++ b/docs/agent-deploy-cloudflare.md
@@ -2,36 +2,14 @@
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:
-
-```text
-This is the GitHub project URL: <repo-url>. Install and deploy this project to Cloudflare for me.
-```
-
-Chinese version:
-
-```text
-这个是 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 or custom domain ownership. The default first-login credentials are `admin` / `admin123`, so a custom password is optional.
-## 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
1. Clone the repository and enter it.
@@ -57,32 +35,16 @@ Chinese version:
4. Prepare deployment resources and `.env.local`.
- By default, run:
-
```sh
bun run deploy:setup
```
- This uses the template credentials `admin` / `admin123`. If the user explicitly provides a custom first-login password, pass that plaintext password through `EDGE_EVER_PASSWORD`; it is not an encrypted password or a password hash:
+ This uses `admin` / `admin123`. If the user explicitly provided another plaintext password, use:
```sh
- # Plaintext first-login password; do not put a hash here.
EDGE_EVER_PASSWORD='<first-login-password>' bun run deploy:setup
```
- `deploy:setup` will:
-
- - copy `.env.local.example` to `.env.local` when needed
- - reuse or create the D1 database
- - create the R2 buckets when needed
- - keep the template password or save the optional plaintext `EDGE_EVER_PASSWORD` override as `EDGE_EVER_AUTH_PASSWORD` in the private, git-ignored `.env.local`; deployment uploads it as a Cloudflare Worker Secret, not a regular plaintext build variable
-
- Password variable meanings:
-
- - `EDGE_EVER_PASSWORD`: optional plaintext override passed temporarily to `deploy:setup`
- - `EDGE_EVER_AUTH_PASSWORD`: login password stored in private `.env.local` and uploaded as a Cloudflare Worker Secret; defaults to `admin123`
- - `EDGE_EVER_AUTH_PASSWORD_HASH`: a PBKDF2 password hash supported only for legacy or advanced configurations; never pass this hash through `EDGE_EVER_PASSWORD`
-
5. Check the deployment inputs.
```sh
@@ -97,7 +59,7 @@ Chinese version:
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` 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. Existing `EDGE_EVER_AUTH_PASSWORD_HASH` configurations remain supported and take precedence when both Secrets exist.
+ This builds the web app, applies remote D1 migrations, deploys the Worker, and uploads `EDGE_EVER_AUTH_PASSWORD` as a Worker Secret. Existing `EDGE_EVER_AUTH_PASSWORD_HASH` configurations remain supported and take precedence when both exist.
7. Verify the result.
@@ -108,45 +70,15 @@ Chinese version:
curl https://<worker-url>/api/openapi.json
```
- Open the site and log in with the configured credentials. Unless overridden, use `admin` / `admin123`. The password can be changed later in Personal Settings. Then create an MCP token from the in-app MCP settings.
+ Open the site and log in with the configured credentials (`admin` / `admin123` by default). Then create an MCP token from the in-app MCP settings.
8. Connect Cloudflare Workers Builds.
- Prefer the automated setup command:
-
```sh
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](cloudflare-workers-builds.md).
-
- 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`:
-
-```sh
-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_AUTH_PASSWORD=admin123
-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:
-
-```sh
-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=admin123
-```
-
-Legacy or advanced installations may use `EDGE_EVER_<INSTANCE>_AUTH_PASSWORD_HASH` instead. Never place either password value in a committed file or a non-secret Cloudflare variable.
+ Follow [Cloudflare Workers Builds](cloudflare-workers-builds.md) for any GitHub authorization, User API Token, or build-token prompt. Complete browser authorization when possible. Do not add a GitHub Actions Worker deployment.
## Blocking Conditions
diff --git a/docs/cloudflare-workers-builds.md b/docs/cloudflare-workers-builds.md
index 26588224..05c12202 100644
--- a/docs/cloudflare-workers-builds.md
+++ b/docs/cloudflare-workers-builds.md
@@ -83,8 +83,6 @@ EDGE_EVER_ROUTE_PATTERN # optional
Existing installations that already use `EDGE_EVER_AUTH_PASSWORD_HASH` may keep it instead of `EDGE_EVER_AUTH_PASSWORD`. If both are present, the hash takes precedence for backward compatibility.
-New installations default to `admin` / `admin123`. The password remains a Build Secret and can be changed later in Personal Settings.
-
For a multi-instance configuration, set `EDGE_EVER_INSTANCE` and the matching scoped variables such as `EDGE_EVER_PROD_D1_DATABASE_ID` instead. The same resolution rules apply in local deployment and Workers Builds.
Workers Builds needs an API token that can deploy Workers, update R2 bindings, and apply D1 migrations. If the automatically created Builds token does not have D1 edit permission, select or create a token with that permission before enabling automated deployments.
diff --git a/docs/cloudflare-workers-builds.zh-CN.md b/docs/cloudflare-workers-builds.zh-CN.md
index a8c557d5..3e2d0d20 100644
--- a/docs/cloudflare-workers-builds.zh-CN.md
+++ b/docs/cloudflare-workers-builds.zh-CN.md
@@ -84,8 +84,6 @@ EDGE_EVER_ROUTE_PATTERN # 可选
已经使用 `EDGE_EVER_AUTH_PASSWORD_HASH` 的旧实例可以继续保留该变量,无需改成 `EDGE_EVER_AUTH_PASSWORD`。为兼容已有实例,两个变量同时存在时哈希优先。
-新实例默认使用 `admin` / `admin123`。密码仍应保存为 Build Secret,部署后可以在个人中心修改。
-
多实例场景则设置 `EDGE_EVER_INSTANCE`,并使用 `EDGE_EVER_PROD_D1_DATABASE_ID` 之类的带实例前缀变量。本地部署和 Workers Builds 使用相同的变量解析规则。
Workers Builds 使用的 API Token 必须拥有 Worker 发布、R2 binding 更新和 D1 migration 所需权限。如果 Cloudflare 自动创建的 Builds token 没有 D1 编辑权限,请选择或新建一个具备该权限的 token。