wocart-setup
Skill420 starsChanged 7 days agoApache-2.0View on GitHub
Setup runbook for a self-hosted Wocart store (formerly CodFlow). An AI agent following it creates the store's Cloudflare resources in the developer's account, fills the gitignored configuration with their real IDs, sets the secrets, migrates and seeds the database, deploys the API server and the dashboard to Cloudflare Workers and the storefront to Cloudflare or Vercel, puts them on the developer's domains, and verifies the result. Use when a developer wants to set up or deploy Wocart (or CodFlow) for the first time. For an install that already exists, use the wocart-update skill instead.
- Reads credentials
- Deletes or force-pushes
- Sends data out
1 other project uses a version of this.
Adopted by
Most recently taken up by
- bighadj22/Wocartword for word, first seen Nov 15, 2026
Other versions1 project uses a version of this.
Word for word · 1
- bighadj22/Wocart★ 420100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository3 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- wocart-updateSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. About 0 are common, 10 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 39
Create new resources for this store: Never bind a D1 database, bucket, KV namespace or queue that already exists in the account: it may …
- Distinctive: line 42
No placeholder may survive: Every ID and URL comes from a command's output or from the developer.
- Very specific: line 47
Wrangler account: If the shell exports a CLOUDFLARE_ACCOUNT_ID the login cannot access, every Wrangler command fails with Authentication …
- Distinctive: line 73
If it lists several accounts, ask which one to use.
- Very specific: line 82
Never create a lockfile inside cod-server, cod-client-astro or cod-shared.
- Very specific: line 86
Ask the developer for a short, unique prefix (<p>, for example mystore).
- Distinctive: line 128
All of these are gitignored.
- Distinctive: line 201
Only comment lines may match.
- Distinctive: line 205
Ask the developer. A store keeps its images where they start, so decide now.
- Very specific: line 248
Put the local values in the .dev.vars files if the developer will also run the store locally (cod-docs/pages/self-hosting/local.mdx).
- Distinctive: line 299
The storefront: Ask: Cloudflare or Vercel.
- Distinctive: line 340
If an address changed from what step 4 assumed, update it everywhere and redeploy what changed:
- Distinctive: line 351
Do not go on past a failing check.
- Very specific: line 361
Always send the Origin header: without it the check passes while real browsers are refused.
- Very specific: line 367
Write a credentials file outside the repository, readable only by the developer (chmod 600, for example ~/wocart-<p>-credentials.md), with …
- Distinctive: line 393
All are off until the merchant turns them on in the dashboard (Apps): Meta Pixel and Conversions API, WhatsApp phone verification …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Wocart setup — agent runbook
Wocart (formerly CodFlow) is a cash-on-delivery commerce platform for Algeria. One store is three Cloudflare Workers sharing one D1 database:
| Part | Folder | Runs on |
| API server | cod-server/ | Cloudflare Workers |
| Merchant dashboard | cod-client-astro/ | Cloudflare Workers |
| Storefront (Theme-00) | cod-astro/theme-00/ | Cloudflare Workers or Vercel |
Folder names, package names, environment variables (COD_*) and some
template defaults still say CodFlow. That is expected; never rename them.
This runbook takes a fresh clone to a working, verified store. Follow it in
order and do not skip a check. The step-by-step guides in the checkout say the
same in more detail: cod-docs/pages/self-hosting/ (local.mdx,
configuration.mdx, deploy.mdx, media.mdx).
Rules for the agent
- Tell the developer what you do, step by step, in plain language. They may not be a developer. Ask before anything they must decide (names, domains, Vercel or Cloudflare, ImageKit or R2) and never guess a value only they have.
- Create new resources for this store. Never bind a D1 database, bucket, KV namespace or queue that already exists in the account: it may belong to another store, and migrating or seeding it would write into its data.
- No placeholder may survive. Every ID and URL comes from a command's output or from the developer.
- Secrets never touch the shell history or a tracked file. Pass them on
standard input from a
chmod 600file outside the repository, and delete the file afterwards. - Wrangler account. If the shell exports a
CLOUDFLARE_ACCOUNT_IDthe login cannot access, every Wrangler command fails withAuthentication error [code: 10000]. Rununset CLOUDFLARE_ACCOUNT_IDonce per session, or prefix commands withenv -u CLOUDFLARE_ACCOUNT_ID.
Before starting — state this to the developer
"I will create a D1 database, an R2 bucket, three KV namespaces and a queue in your Cloudflare account, fill your configuration files with their IDs, migrate and seed the database, and deploy the API server, the dashboard and the storefront. The API and the storefront need your own domain on Cloudflare. Nothing is left on example values."
Prerequisites
- Node.js 22.12 or newer, and npm.
- A Cloudflare account with R2 enabled (dashboard → R2; it needs a payment card on file, the free tier is enough).
- A domain on Cloudflare for the API (for example
api.mystore.com) and, for a storefront on Cloudflare, for the shop (mystore.com). See step 8. Wrangler signed in:
npx wrangler whoami # not signed in: npx wrangler loginIf it lists several accounts, ask which one to use.
Step 1 — Install
npm ci # repo root: API server, dashboard, shared code
(cd cod-astro/theme-00 && npm ci) # the storefront has its own lockfileNever create a lockfile inside cod-server, cod-client-astro or cod-shared.
Step 2 — Choose the names
Ask the developer for a short, unique prefix (<p>, for example mystore).
Names must not collide with another store in the same account: Worker names,
queue names and Workflow names are unique per account, and deploying a
duplicate overwrites or breaks the other store.
| What | Name |
| API server Worker | <p>-server (deployed as <p>-server-production, see step 7) |
| Dashboard Worker | <p>-dashboard |
| Storefront Worker | <p>-storefront |
| D1 database | <p>-db |
| R2 bucket | <p>-media |
| Queue | <p>-events |
| Workflows | <p>-lp-image-upload-workflow, <p>-review-media-workflow |
Step 3 — Create the resources
npx wrangler d1 create <p>-db # note database_id
npx wrangler r2 bucket create <p>-media
npx wrangler kv namespace create <p>-rate-limit # API server: RATE_LIMIT
npx wrangler kv namespace create <p>-oauth # API server: OAUTH_KV (MCP sign-in)
npx wrangler kv namespace create <p>-dashboard-rate-limit # dashboard: RATE_LIMIT_KV
npx wrangler queues create <p>-eventsRecord the D1 database_id (a UUID) and the three KV ids (32 hex
characters). If a name is taken, choose another; never reuse the existing
resource. If an ID cannot be read from the output, stop and show the output
to the developer.
Step 4 — Fill the configuration
cp .env.example .env
cp cod-server/wrangler.toml.example cod-server/wrangler.toml
cp cod-client-astro/wrangler.toml.example cod-client-astro/wrangler.toml
cp cod-server/.dev.vars.example cod-server/.dev.vars
cp cod-client-astro/.dev.vars.example cod-client-astro/.dev.vars
cp cod-astro/theme-00/.dev.vars.example cod-astro/theme-00/.dev.varsAll of these are gitignored. Confirm it before writing any real value:
git status --short .env cod-server/wrangler.toml cod-client-astro/wrangler.toml
# must print nothingRoot .env — read by the database, seed, storage and storefront deploy
scripts:
COD_ACCOUNT_ID=<account id>
COD_DB_NAME=<p>-db
COD_R2_BUCKET_NAME=<p>-media
COD_SERVER_URL=https://api.<domain> # the API's public address (step 8)cod-server/wrangler.toml. The top of the file is local development; the
[env.production] blocks are what the deployed API server uses. In both:
name = "<p>-server"(top line only);[[d1_databases]]:database_name = "<p>-db"and itsdatabase_id(the top-level one is also what the migration scripts read);[[r2_buckets]]:bucket_name = "<p>-media";[[kv_namespaces]]:RATE_LIMITandOAUTH_KVwith their IDs;- the queue:
queue = "<p>-events"in the producer and the consumer; - the two
[[workflows]]:name = "<p>-lp-image-upload-workflow"andname = "<p>-review-media-workflow", keeping eachbindingandclass_name; [[ratelimits]]: anamespace_idno other store in the account uses (any positive integer).
[env.production] has one vars = { … } line, and it replaces the top-level
[vars] entirely: every production value goes on that line. Set the real
values (the domains of step 8):
ENVIRONMENT = "production"
WORKER_URL = "https://api.<domain>"
WORKER_SELF_URL = "https://api.<domain>/"
BETTER_AUTH_URL = "https://dashboard.<domain>/api/auth"
ALLOWED_ORIGINS = "https://dashboard.<domain>,https://<domain>"
STOREFRONT_URL = "https://<domain>"BETTER_AUTH_URL must be the dashboard's address: the API server checks every
dashboard request against the dashboard's public keys there. ENVIRONMENT =
"production" turns on the ALLOWED_ORIGINS check; without it the API answers
any website. The media values come in step 5.
cod-client-astro/wrangler.toml:
name = "<p>-dashboard";[[d1_databases]]: the samedatabase_nameanddatabase_id;[[kv_namespaces]]RATE_LIMIT_KV: the<p>-dashboard-rate-limitID;[vars]:PUBLIC_APP_URL = "https://dashboard.<domain>",PUBLIC_API_URL = "https://api.<domain>", andPUBLIC_TRUSTED_ORIGINSlisting every address the dashboard is opened from (its custom domain, and itsworkers.devaddress if used).
PUBLIC_API_URL is written into the dashboard's code when it is built: set it
in wrangler.toml (production) and in cod-client-astro/.dev.vars (local,
http://localhost:8787), never in cod-client-astro/.env, which the build
ignores.
cod-astro/theme-00/wrangler.jsonc: "name": "<p>-storefront".
Check that no example value is left:
grep -n "= \"codflow-server\"\|= \"codflow-dashboard\"\|00000000\|<your-\|your_\|your-store\|example\.com\|codflow-images\|codflow-os-db\|codflow-db\|codflow-events\|\"lp-image\|\"review-media" \
cod-server/wrangler.toml cod-client-astro/wrangler.tomlOnly comment lines may match. Fix every other hit before going on.
Step 5 — Choose where images live
Ask the developer. A store keeps its images where they start, so decide now.
ImageKit (recommended: fast in Algeria). They need the URL endpoint (
https://ik.imagekit.io/<id>), the public key and the private key (ImageKit → Developer options). In[env.production]vars:MEDIA_HOST = "imagekit" MEDIA_DELIVERY = "imagekit" MEDIA_ORIGIN = "https://ik.imagekit.io/<id>/stores/<p>" IMAGEKIT_PUBLIC_KEY = "public_…" IMAGEKIT_FOLDER = "/stores/<p>"The private key is a secret (step 7). With R2 instead, remove the two
IMAGEKIT_*keys from the line.Cloudflare R2 on their domain. Connect a custom domain to the bucket (
media.<domain>, R2 → bucket → Settings) and turn on Images → Transformations for that zone, or resized pictures do not load:MEDIA_HOST = "r2" MEDIA_DELIVERY = "cloudflare" MEDIA_ORIGIN = "https://media.<domain>"
The R2 bucket is needed either way: uploads wait there before they are
prepared. Local development needs nothing: the top-level values serve the
local bucket through the local server. The storefront takes no media setting;
the API tells it. Details: cod-docs/pages/self-hosting/media.mdx.
Step 6 — Generate the keys
Generate each once and keep it for the credentials file (step 10):
openssl rand -hex 32 # STORE_API_KEY the storefront's key to the API
openssl rand -hex 32 # BETTER_AUTH_SECRET the dashboard's sign-in secret
openssl rand -hex 32 # MCP_LOGIN_TICKET_SECRET the same on the API server and the dashboard
openssl rand -hex 32 # REVIEW_UPLOAD_SECRET the API server's review uploads
(cd cod-astro/theme-00 && npx astro create-key) # ASTRO_KEY the storefront build's keyPut the local values in the .dev.vars files if the developer will also run
the store locally (cod-docs/pages/self-hosting/local.mdx).
Step 7 — Database, then the three Workers
The database. Migrate the local copy too: the admin seeder writes both.
cd cod-server
npm run db:migrate:local
npm run db:migrate:remote
STORE_API_KEY=<STORE_API_KEY> npm run db:seed:remote
npm run r2:lifecycledb:seed:remote creates the store, its API key (it keeps only a hash), the
menus, the default collections, the four legal pages and a shipping profile.
Running it again changes nothing the store has. The starter catalog with
photos is not part of a self-hosted setup: its pictures are not in this
repository. r2:lifecycle deletes uploads that were never used, after a day.
The API server. It deploys with its production settings, as
<p>-server-production:
npm run deploy -- --env productionThen its secrets, on the same Worker:
printf '%s' '<value>' > ~/.wocart-secret && chmod 600 ~/.wocart-secret
npx wrangler secret put MCP_LOGIN_TICKET_SECRET --env production < ~/.wocart-secret
# repeat for REVIEW_UPLOAD_SECRET, and IMAGEKIT_PRIVATE_KEY with ImageKit
rm ~/.wocart-secretThe dashboard.
cd ../cod-client-astro
npm run deploy
npx wrangler secret put BETTER_AUTH_SECRET < ~/.wocart-secret # same file pattern
npx wrangler secret put MCP_LOGIN_TICKET_SECRET < ~/.wocart-secret # the API server's value
ADMIN_EMAIL=<email> ADMIN_NAME=<name> npm run seed:admin:remotenpm run deploy builds first, keeps local values out of the build, and stops
if the result would call localhost. seed:admin:remote prints the admin's
password and a merchant API key once: copy them into the credentials file.
The storefront. Ask: Cloudflare or Vercel.
Cloudflare:
cd ../cod-astro/theme-00 ASTRO_KEY=<ASTRO_KEY> npm run deploy npx wrangler secret put STORE_API_KEY < ~/.wocart-secretThe deploy takes
COD_SERVER_URLfrom the root.envand refuses alocalhostvalue. PassingASTRO_KEYkeeps it the same across deploys, so pages already cached keep working. This Worker has noworkers.devaddress: it is reached only through the domain added in step 8.Vercel: from
cod-astro/theme-00, link a project and set its environment, then deploy:npx vercel link printf 'vercel' | npx vercel env add DEPLOY_TARGET production printf '%s' 'https://api.<domain>' | npx vercel env add COD_SERVER_URL production npx vercel env add STORE_API_KEY production < ~/.wocart-secret npx vercel env add ASTRO_KEY production < ~/.wocart-secret npx vercel --prodDEPLOY_TARGET=vercelis what makes the build produce a Vercel site.
Step 8 — Domains
Cloudflare blocks one *.workers.dev Worker from calling another (error
1042), so the API must be on the developer's domain. In the Cloudflare
dashboard, open each Worker → Settings → Domains & Routes → Add → Custom
domain:
| Worker | Domain |
<p>-server-production | api.<domain> |
<p>-dashboard | dashboard.<domain> (its workers.dev address also works) |
<p>-storefront | <domain> (required on Cloudflare) |
If an address changed from what step 4 assumed, update it everywhere and redeploy what changed:
| File | Values | Redeploy |
cod-server/wrangler.toml [env.production] | WORKER_URL, WORKER_SELF_URL, BETTER_AUTH_URL, ALLOWED_ORIGINS, STOREFRONT_URL | npm run deploy -- --env production |
cod-client-astro/wrangler.toml | PUBLIC_APP_URL, PUBLIC_API_URL, PUBLIC_TRUSTED_ORIGINS | npm run deploy (rebuilds) |
root .env | COD_SERVER_URL | the storefront's deploy |
Step 9 — Verify
Do not go on past a failing check.
| Check | Expected |
curl -s -o /dev/null -w "%{http_code}\n" https://api.<domain>/api/docs | 200 |
curl -s -X POST https://dashboard.<domain>/api/auth/sign-in/email -H "Content-Type: application/json" -H "Origin: https://dashboard.<domain>" -d '{"email":"<admin>","password":"<password>"}' | 200 and the user |
| The developer signs in to the dashboard | the orders screen loads |
| The developer opens the storefront | the home page shows the store |
| The developer places a test order on the storefront | it appears in the dashboard's orders |
Always send the Origin header: without it the check passes while real
browsers are refused. While a check fails, read the Worker's errors:
npx wrangler tail <worker-name> --format pretty.
Step 10 — Hand over
Write a credentials file outside the repository, readable only by the
developer (chmod 600, for example ~/wocart-<p>-credentials.md), with every
value in its own code block: the admin email and password, the merchant API
key, STORE_API_KEY, BETTER_AUTH_SECRET, MCP_LOGIN_TICKET_SECRET,
REVIEW_UPLOAD_SECRET, ASTRO_KEY, and the three addresses. Read values from
the files and command output, never retype them. Show secrets in the chat at
most once, and tell the developer to move them to a password manager.
Then print what was created:
| Resource | Name | ID | Where it is bound |
| D1 | <p>-db | <uuid> | both wrangler.toml files |
| R2 | <p>-media | — | cod-server/wrangler.toml |
| KV | <p>-rate-limit, <p>-oauth | <ids> | cod-server/wrangler.toml |
| KV | <p>-dashboard-rate-limit | <id> | cod-client-astro/wrangler.toml |
| Queue | <p>-events | — | cod-server/wrangler.toml |
| Workers | <p>-server-production, <p>-dashboard, <p>-storefront | — | their domains |
And tell them how updates work: "When Wocart publishes an update, ask your AI
agent to update Wocart. It follows the wocart-update skill in this
repository: it keeps your resources, secrets and data, applies what is new,
and redeploys. You never run this setup again."
Optional features
All are off until the merchant turns them on in the dashboard (Apps):
Meta Pixel and Conversions API, WhatsApp phone verification (DZVerify), bot
protection (Turnstile), email (Sendili), the WhatsApp button, Telegram
notifications and reviews. Carriers are added under delivery companies;
Yalidine and ZR Express each need their webhook secret. Offer them after
step 9, never set them up unasked. Guides: cod-docs/pages/features/.
Running locally
cd cod-server && npm run db:setup:local && npm run dev # http://localhost:8787
cd cod-client-astro && npm run seed:admin && npm run dev # http://localhost:4321
cd cod-astro/theme-00 && npm run dev -- --port 4322 # http://localhost:4322Local data lives in .wrangler-shared/ at the repository root, shared by the
API server and the dashboard. Signing in against an unmigrated local database
is the usual reason the local dashboard "does not work".
Troubleshooting
| Problem | Cause | Fix |
Every Wrangler command: Authentication error [code: 10000] | A stale CLOUDFLARE_ACCOUNT_ID in the shell | unset CLOUDFLARE_ACCOUNT_ID |
wrangler r2 bucket create fails | R2 is not enabled | Enable R2 in the dashboard (payment card, free tier), retry |
| Deploy fails on a binding | An example value is left | Re-run the step 4 check |
| Deploy fails: a Workflow or queue already exists | The name belongs to another store in the account | Use this store's prefix (step 2) |
| Sign-in answers 500 | The deployed database is not migrated | npm run db:migrate:remote in cod-server |
Sign-in answers 403 INVALID_ORIGIN | The dashboard's address is not in PUBLIC_TRUSTED_ORIGINS | Add it, npm run deploy in cod-client-astro |
| Signed in, but every screen fails with 401 | The API server cannot check the dashboard's sign-in | BETTER_AUTH_URL must be the dashboard's /api/auth address and WORKER_SELF_URL the API's own, in [env.production]; redeploy the API |
The dashboard calls localhost | It was built with the local PUBLIC_API_URL | npm run deploy in cod-client-astro (it rebuilds) |
| The storefront shows an unavailable store | It cannot reach the API | COD_SERVER_URL must be the API's domain (not workers.dev, not localhost), and STORE_API_KEY the key given to db:seed:remote |
| The storefront has no address | Theme-00 does not use workers.dev | Add its custom domain (step 8) |
Storefront deploy refuses COD_SERVER_URL | The root .env still says localhost | Set the API's domain, deploy again |
Image uploads fail with MEDIA_NOT_CONFIGURED | A media value or the ImageKit secret is missing | Step 5 and step 7, then redeploy the API |
| Resized pictures do not load on R2 | Images Transformations are off for the zone | Turn them on for the media domain's zone |
The local storefront crashes with Missing field 'moduleType' | Two Vite versions installed | rm -rf node_modules && npm ci (repo root, and in cod-astro/theme-00) |
Address already in use on 8787 or 4321 | Another dev server is running | Stop it, or run the storefront with --port 4322 |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

