01. Before You Start

Do not skip this chapter.

If you do not prepare this part properly, you will almost certainly get stuck later.

1. What you are actually deploying

ZShip is not a single-page project.

It is a full system that you eventually deliver to users, including at least:

• 10 backend Workers
• 2 frontend apps that users will interact with
• 9 D1 databases
• 1 KV namespace used by the payment service
• 1 R2 bucket used by the CDN service

So you are not deploying just one website.

You are deploying a Cloudflare-based system made of frontend apps, an admin backend, microservices, databases, and storage.

2. What accounts you need

At minimum, prepare:

• A Cloudflare account
• A copy of the Git repository
• A machine that can run Node.js

Optional accounts:

• A Stripe account if you want real payments
• A Creem account if you want Creem payments
• A Google OAuth app if you want Google login

3. Decide how you will obtain the source code

This is one of the easiest choices to overlook at the start, but it directly affects long-term maintenance cost.

You have two options.

Option A: GitHub Fork

How it works:

1. Open the official template repository
2. Click the Fork button in the top-right corner of GitHub
3. Fork the repository into your own account or organization
4. Clone your forked repository locally

Advantages:

• It preserves the relationship to the official template repo
• Future upstream updates are easier to sync manually
• It is the best fit if you want to maintain your product on top of the template for a long time

Disadvantages:

• It will not update automatically
• Future upstream updates still require manual handling

Option B: Copy the code and create your own repo

How it works:

1. Download the official template code
2. Remove the original Git history or do not keep the original repo relationship
3. Create a brand-new repository under your own GitHub account
4. Push the code there

Advantages:

• The repository history feels more like your own standalone project
• Some teams prefer this setup psychologically and operationally

Disadvantages:

• You do not keep a ready-made upstream sync path
• Following future official changes becomes manual comparison and merging work

Which one we recommend

Recommended:

• Choose GitHub Fork

Why:

• The official template will continue to receive updates
• A fork preserves your path for adopting those updates later
• For most users, this results in the lowest long-term maintenance cost

But remember:

• Fork does not automatically give you future template updates

When the official template changes:

• You still need to sync upstream manually
• On GitHub you can use Sync fork
• Or do it locally with fetch plus merge or rebase

4. What you need installed locally

Make sure your machine already has:

• Node.js 22 or newer
• pnpm
• Git

After installation, run:

node -v
pnpm -v
git --version

All three commands should return valid versions before you continue.

5. Start the Dev Console first

If this is your first time touching the project, run this before going further:

pnpm dev:console

Then visit:

http://localhost:3900

You do not need to click every feature yet.

Just make sure you can see these three tabs:

• Getting Started
• Local Startup
• Deploy Cloudflare

That will reduce your later debugging cost dramatically.

6. Pull the repository locally

If you already have the repo, you can skip this section.

If not, clone your repository:

git clone <your-repository-url>
cd zship

If you chose Fork

The repository URL here should be your own forked repository.

It should not be the official repository URL.

If you chose “create a new repo yourself”

Then this URL should be your own brand-new repository.

After that, install dependencies:

pnpm install

Installation may take a while. That is normal.

If pnpm install fails, do not move on to later steps until dependencies are fixed.

7. Log in to Wrangler

Wrangler is Cloudflare’s official command-line tool.

This project uses it to create and deploy Workers, Pages, D1, KV, and R2 resources.

Run this from the repository root:

npx wrangler login

Your browser will open a Cloudflare authorization page.

After authorization completes, run:

npx wrangler whoami

If you can see your Cloudflare account information, Wrangler login is working.

8. What not to change on the first deployment

Do not rename these Workers

• zship-node1-auth
• zship-node2-support
• zship-node3-pay
• zship-node4-notify
• zship-node5-blog
• zship-node6-cdn
• zship-node7-site
• zship-node8-prompt
• zship-node9-checkin
• zship-node10-ai

Do not rename these Pages projects

• web
• admin

9. Checklist before you leave this chapter

Confirm that:

• You have decided whether to use Fork or create your own repository
• You know how to start pnpm dev:console
• You have the repository cloned locally
• You have run pnpm install
• You have run npx wrangler login
• You have run npx wrangler whoami
• You understand that the first pass should keep the default service names

If any item above is still unfinished, do not continue to the next chapter yet.