Zudo Works

Self-hosting and configuration

Zudo Works ships as a pnpm monorepo: apps/shop-api (NestJS on Fastify), apps/shop-web (Vue 3), packages/shop-domain (pure rules and schemas), packages/shop-db (PostgreSQL repositories and forward-only SQL migrations), tests/shop-e2e (Playwright).

Quick start (development)

cp .env.example .env
docker compose -f infra/compose/compose.yaml up -d       # PostgreSQL (+ Redis)
set -a; . ./.env; set +a
pnpm --filter @zudo/shop-db migrate                      # creates zudo_shop and applies migrations
pnpm --filter @zudo/shop-api dev                         # API on http://127.0.0.1:3100
pnpm --filter @zudo/shop-web dev                         # UI on http://127.0.0.1:5174

Production (single VM): infra/compose/shop.compose.yaml + Caddyfile (automatic HTTPS), shop.env from shop.env.example, nightly shop-backup.sh (pg_dump). Or run the API image (infra/docker/shop-api.Dockerfile) behind any proxy with SHOP_TRUST_PROXY=true, PostgreSQL, Redis for sessions and Cloudflare R2 for files (SHOP_STORAGE_DRIVER=r2). The web app is served by the API (SHOP_WEB_DIST) or by a static host (Cloudflare Pages) pointed at the API origin. Migrations are applied with migrateShop at start-up or by the migrate script; files already applied are never edited (add a new migration instead).

Zudo AI (optional): set SHOP_AI_BASE_URL to an OpenAI-compatible Chat Completions endpoint, SHOP_AI_MODEL to a tool-calling instruct model and SHOP_AI_API_KEY to the provider's key. The production default is Fireworks AI (https://api.fireworks.ai/inference/v1, accounts/fireworks/models/gpt-oss-120b, a reasoning model asked for reasoning_effort: low — SHOP_AI_REASONING_EFFORT — whose reasoning is never shown or stored): hosted, no data retention on the Chat Completions API (the Responses API, which stores requests for 30 days, is never used). A self-hosted Ollama behind your own HTTPS proxy works the same way (optional). In production the URL must be https and the key must be set; unset = the assistant is hidden. Details in docs/mvp-sheet-metal/DEPLOYMENT.md §11.

Quality gates: pnpm lint, pnpm typecheck, pnpm build, pnpm test (unit), pnpm test:integration (PostgreSQL via Testcontainers), pnpm test:e2e (Playwright), with pnpm format:check (Prettier). Environment variables are listed in Appendix D.

Last updated