Deployment Guide

This guide covers deployment of the core delivery only:

Frontend: apps/web (user site), apps/admin (admin console)
Backend: node1-auth ~ node10-ai (10 Workers)

Value-added services (e.g. AI Provider Service) are not included. See Value-Added Services.

Choose your path

In the documentation sidebar, every step for both tracks is listed under Deployment Guide. Pick one track below and follow only those pages in order.

ZShip supports two ways to set up local development and deploy to Cloudflare:

CLI (manual commands)

Use this path if:

You are on a base/minimal setup without Dev Console
You prefer the command line or need to script deployments (CI, automation)
You want full control over each step

You will run pnpm install, wrangler d1 create, wrangler deploy, and similar commands manually in your terminal.

Start here: CLI: Before You Start

Dev Console (UI)

Use this path if:

You have the full ZShip template with Dev Console
You prefer a graphical interface for local startup and deployment
You want fewer commands to remember and fewer steps to miss

You will run pnpm dev:console once, then use the browser UI for setup, migrations, service startup, and Cloudflare deployment.

Start here: Meet the Dev Console

Please read your chosen path 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

Reading order by track

If you use the CLI

If you use Dev Console

Troubleshooting and ops index

Topic	Doc
Launch checklist, Observability, CDN/R2, email & webhooks, common errors	Launch Checks
Dev Console vs Cloudflare Dashboard	Meet the Dev Console §4
Secrets and repo safety	Important Notes — Security