Doc

This set of docs is written for people who may be using ZShip for the first time, deploying to Cloudflare for the first time, or even touching a monorepo for the first time.

If you only want the one-line version, the full process is:

1. Prepare your Cloudflare account, local Node.js, pnpm, and Wrangler.
2. Open the Dev Console first so you understand the built-in tooling.
3. Create the required resources in Cloudflare.
4. Deploy the backend Workers first.
5. Deploy the frontend Pages apps next, focusing on web and admin.
6. Bind domains, finish environment variables, then log in to the admin to initialize the system.

Please read the guide in order the first time through.

Two ways to get the source code

When users receive this template, there are usually two approaches.

Option 1: GitHub Fork

This means:

• The user directly forks the official repository into their own GitHub account or organization.

Advantages:

• It keeps the upstream relationship with the official repository.
• It is easier to manually sync future template updates.
• It fits the common workflow where the official template keeps evolving and users build their own product on top of it.

Disadvantages:

• It does not update automatically.
• Users still need to sync upstream changes by hand.
• If a user changes a lot locally, future syncs can create conflicts.

Option 2: Copy the code and create a new repository

This means:

• The user downloads the official codebase.
• They then create a brand-new Git repository under their own account.

Advantages:

• The repository history looks cleaner.
• Some teams prefer the feeling that this is fully their own project from day one.

Disadvantages:

• There is no upstream relationship to the official template.
• Future official updates will not have a ready-made sync path.
• Keeping up with template improvements usually means manual compare-and-copy work.

Recommended approach

We recommend users start with:

• GitHub Fork

Why:

• The official template will continue to evolve.
• A fork at least preserves a clean path for manually syncing future official changes.
• For most users, long-term maintenance cost is lower than copying the repo into a totally separate history.

But this point must be crystal clear:

• Fork does not mean you automatically receive official updates.

In practice that means:

• The official template can keep moving.
• Users will not receive those changes automatically.
• Users must sync upstream manually.

What this guide covers

This guide covers the Cloudflare deployment path for:

• backend/node1-auth-service
• backend/node2-support-service
• backend/node3-pay-service
• backend/node4-notify-service
• backend/node5-blog-service
• backend/node6-cdn-service
• backend/node7-site-service
• backend/node8-prompt-service
• backend/node9-checkin-service
• backend/node10-ai-service
• apps/web
• apps/admin

Recommended reading order

1. Meet the Dev Console
2. Before You Start
3. Prepare Cloudflare Resources
4. Deploy Backend Workers
5. Deploy Frontend Pages
6. Bind Domains and Environment Variables
7. Initialize Your System
8. Launch Checks and Common Errors

Four rules to remember first

1. Do not rename Workers on the first deployment

The service bindings in this repo are already wired into the various wrangler.jsonc and wrangler.toml files.

Examples:

• zship-node1-auth
• zship-node2-support
• zship-node3-pay
• zship-node10-ai

If you rename services during the first deployment, you will create a pile of binding errors for yourself.

For the first pass, keep the repository defaults.

2. Do not rename Pages projects on the first deployment

The frontend projects currently assume the standard names below:

• admin

Do not get clever and rename them on the first pass.

3. Use the default app_key first

For the first successful end-to-end run, start with:

• demo

Why:

• Many places in the repository assume that value by default.

Once the whole system is confirmed working, switch the frontend environment variables to your real app_key.

4. When you hit an error, do not change five things at once

Change one thing, then retry.

Otherwise, by the time it breaks differently, you will not know which edit actually caused the problem.