EdgeEver Manual Online Deployment Guide

This document provides a detailed step-by-step guide for deploying EdgeEver online via GitHub and Cloudflare. The entire setup is performed in your browser—no local code installation or environment setup is required.

💡 Zero-Cost Self-Hosting: Built completely on Cloudflare's free tiers—no VPS or server rentals needed, and no Docker or SSL certificate setup required.

Prerequisites

GitHub Account (for Forking the repository and enabling automated updates)
Cloudflare Account (for hosting Worker logic, SQLite D1 database, and R2 storage)

Step-by-Step Deployment Guide

Step 1: Fork the Repository & Enable Actions

Visit the official EdgeEver repository: https://github.com/tianma-if/edgeever.
Click the Fork button at the top right to fork the repository into your GitHub account.
Go to your Forked repository, navigate to the Actions tab, and click "I understand my workflows, go ahead and enable them" to activate automated workflows.

Step 2: Create Storage & Database Resources in Cloudflare

Log into your Cloudflare Dashboard:

Create a D1 Database:
- Navigate to Workers & Pages -> D1, then click Create database.
- Database name: exactly edgeever, then click Create.
Create an R2 Bucket (for note attachments & images):
- Navigate to Workers & Pages -> R2, then click Create bucket.
- Bucket name: exactly edgeever-resources, then click Create bucket.

In Cloudflare Dashboard, navigate to Workers & Pages -> Overview, click Create application -> Pages / Workers (Import Git Repository).
Click Connect to Git, authorize Cloudflare, and select your Forked edgeever repository.
Project settings:
- Production branch: main
- Root directory: Leave blank or default /
Under Settings -> Variables and Secrets, add the login password:

Type	Name	Value	Purpose
Secret	`EDGE_EVER_AUTH_PASSWORD`	Set a strong admin password	Initial login credential

EDGE_EVER_AUTH_PASSWORD is a Worker runtime Secret, not a Workers Builds variable. The standard deploy command reuses and verifies this Secret; do not duplicate the password in build variables.

The repository's deployment command creates the DB and RESOURCES bindings from the standard resource names. Do not edit wrangler.toml or add duplicate bindings in the Dashboard.

Existing deployments created from older instructions do not need to rename or migrate a custom R2 bucket. When no explicit Builds variable is set, the deploy command reads the live Worker's current RESOURCES binding and keeps using that bucket automatically.

Step 4: Set Build Commands & Start Build

In the Cloudflare project Build settings, configure:

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

Click Save and Deploy to trigger the initial build.

The deploy command automatically looks up the D1 UUID by the edgeever database name. Keep the tracked wrangler.toml unchanged; deployment rejects instance-specific values committed there. The Workers Builds API token must have D1 read/edit permission.

After publishing, the CI deployment records the actual public target reported by Wrangler and requests its /api/health endpoint. The build fails if the live Worker is missing its DB or RESOURCES binding, uses an unprepared D1 database, or does not return a healthy response.

After deployment completes, Cloudflare will assign a default domain (e.g., https://edgeever.your-subdomain.workers.dev).
Visit the health check endpoint in your browser: https://<your-domain>/api/health, and confirm it returns HTTP 200 with:
```
{ "ok": true }
```
Open the homepage, log in with your configured administrator username (default: admin) and EDGE_EVER_AUTH_PASSWORD, and start using EdgeEver!
Go back to your Fork's Actions tab on GitHub and manually trigger Update deployed EdgeEver once to ensure upstream updates will sync properly in the future.

Advanced Configuration: Update Channels

By default, Update deployed EdgeEver follows official stable Release tags. To follow upstream main (Edge preview builds), set this GitHub Repository Variable on the Fork (Settings → Secrets and variables → Actions → Variables):

EDGE_EVER_UPDATE_CHANNEL=edge

You can also pick stable / edge when manually running the workflow.

Advanced Configuration: Instance Settings

Ordinary deployments do not need these settings. To customize an instance, add non-secret values under Settings -> Builds -> Variables and secrets instead of changing repository files:

Build variable	Purpose
`EDGE_EVER_AUTH_USERNAME`	Administrator username; defaults to `admin`
`EDGE_EVER_WORKER_NAME`	Worker name
`EDGE_EVER_D1_DATABASE_NAME`	D1 database name; its UUID is discovered automatically
`EDGE_EVER_D1_DATABASE_ID`	Optional UUID fallback when discovery is unavailable
`EDGE_EVER_R2_BUCKET_NAME`	Optional explicit production R2 bucket override; upgrades otherwise reuse the live binding
`EDGE_EVER_R2_PREVIEW_BUCKET_NAME`	Preview R2 bucket name
`EDGE_EVER_WORKERS_DEV`	Enable or disable the `workers.dev` route
`EDGE_EVER_CUSTOM_DOMAIN` / `EDGE_EVER_ROUTE_PATTERN`	Custom routing

Passwords and other credentials remain Worker runtime Secrets and must never be added to Builds variables. An advanced local deployment may instead use the git-ignored .env.local or an external WRANGLER_CONFIG file.

Troubleshooting

Initial build failed: Check the Worker Deployments log. Verify that the standard resources are named exactly edgeever and edgeever-resources, and that the Workers Builds API token has D1 read/edit permission. For an intentionally different D1 database, set EDGE_EVER_D1_DATABASE_NAME; add EDGE_EVER_D1_DATABASE_ID only if automatic UUID discovery is unavailable.
Updates not syncing:
1. On the Fork Actions tab, enable Update deployed EdgeEver (scheduled workflows are off by default on public forks).
2. Run it once with Run workflow. Open the job Summary: it states the upstream target version and whether the fork was updated, already aligned, or failed.
3. A green run with Already on upstream target means Git already matches that channel — not a broken skip. If the live site is still old, check Cloudflare Deployments commit SHA, or re-run with force_redeploy.
4. Prefer this workflow over GitHub Sync fork for day-to-day upgrades.
5. If an old updater fails with without workflows permission, use Sync fork once as the repository owner, then re-run Update deployed EdgeEver. The current updater preserves .github/workflows/**, so later product updates do not hit this permission boundary.
Push succeeded but site unchanged: Confirm Workers Builds ran for the new main SHA. Optionally add repository secret EDGE_EVER_CLOUDFLARE_DEPLOY_HOOK_URL so the workflow can call a Deploy Hook after publish.
Reset or Manual Recovery: See the Cloudflare Manual Deployment Guide.

7.5 KiB Raw Blame History