Local Development

The full Zelly stack runs on your machine via docker-compose. Aurora (MySQL) is NOT run locally — services connect to the publicly-accessible staging Aurora endpoint. Redis and ClickHouse run in local Docker containers.

Prerequisites

One-time machine setup

1. Clone all repos as siblings

   All repos must live in the same parent directory. docker-compose uses relative paths between them.

   bash — create workspace

   copy

   mkdir zelly && cd zelly
   
   git clone git@github.com:zelly-in/terraform.git
   git clone git@github.com:zelly-in/backend-api-fastify-nova.git
   git clone git@github.com:zelly-in/customer-panel-neptune.git
   git clone git@github.com:zelly-in/internal-admin-panel-orion.git
   git clone git@github.com:zelly-in/store-events-consumer.git
   git clone git@github.com:zelly-in/storefront-astro-titan.git
   git clone git@github.com:zelly-in/seller-panel-react-atlas.git
   git clone git@github.com:zelly-in/zelly-checkout.git        # CF Worker — optional

   Expected layout:

   zelly/                              # workspace root — NOT a git repo
   ├── terraform/
   ├── backend-api-fastify-nova/
   ├── customer-panel-neptune/
   ├── internal-admin-panel-orion/
   │   ├── backend/
   │   └── frontend/
   ├── store-events-consumer/
   ├── storefront-astro-titan/
   └── seller-panel-react-atlas/

2. Add the shell alias

   Add to your ~/.zshrc, ~/.bashrc, or PowerShell profile. Run all zdev commands from the workspace root.

   macOS / Linux (~/.zshrc)

   copy

   alias zdev='docker compose -f terraform/local-dev/docker-compose.yml --project-directory . --env-file terraform/local-dev/.env'

   Windows PowerShell profile ($PROFILE)

   copy

   function zdev { docker compose -f terraform/local-dev/docker-compose.yml --project-directory . --env-file terraform/local-dev/.env @args }

   Reload your shell or open a new terminal after adding.

3. Add hosts entries

   The local Caddy proxy routes *.test domains to the right container. Your OS needs to know they resolve to localhost.

   macOS / Linux (/etc/hosts)

   copy

   sudo sh -c 'echo "127.0.0.1 zelly-nova.test zelly-customer.test zelly-orion.test zelly.test zelly-bull.test zelly-redis.test zelly-seller.test zelly-admin.test" >> /etc/hosts'

   Windows — open Notepad as Administrator, edit C:\Windows\System32\drivers\etc\hosts, add:

   127.0.0.1 zelly-nova.test zelly-customer.test zelly-orion.test zelly.test zelly-bull.test zelly-redis.test zelly-seller.test zelly-admin.test

4. Free port 80 (Windows only)

   IIS holds port 80 by default. Run once as Administrator:

   cmd as Administrator

   copy

   net stop "World Wide Web Publishing Service"
   net stop "IIS Admin Service"

   If neither service exists, skip this step.

5. Create terraform/local-dev/.env

   This is the single source of truth for all local credentials. docker-compose reads it via --env-file and injects values into every service.

   bash — from workspace root

   copy

   cp terraform/local-dev/.env.example terraform/local-dev/.env
   # Open terraform/local-dev/.env and fill in:
   #   DB_HOST     — staging Aurora endpoint (from AWS console or terraform output)
   #   DB_USER     — root
   #   DB_PASSWORD — get from team 1Password
   # Leave REDIS_PASSWORD and CLICKHOUSE_PASSWORD as-is (localredis / localclickhouse)

   !

   Do NOT add DB_HOST, DB_USER, or DB_PASSWORD to individual service .env files. docker-compose injects them from terraform/local-dev/.env via the environment: block. Service .env files only contain service-specific config (JWT secrets, API keys).

   Service .env files are optional — the stack boots without them (required: false). Copy only if you need to override a service-specific default.

6. Place the Firebase service account for fastify-nova

   fastify-nova uses Firebase Admin SDK for auth token verification. The JSON credentials file must exist at:

   backend-api-fastify-nova/service-account-creds-private.json

   Get it from the team 1Password vault. The Dockerfile copies it into the image at build time. Without it, nova exits immediately with ERR_MODULE_NOT_FOUND.

Starting the stack

From the workspace root:

zdev up          # start everything, show logs
zdev up -d       # start detached (background)

Partial stacks

# Infrastructure only — connect your local Node process to Redis + ClickHouse
zdev up redis clickhouse

# Backend services only (no frontends)
zdev up redis clickhouse fastify-nova customer-panel orion-backend events-consumer proxy

# Single service + proxy
zdev up redis fastify-nova proxy

Service URLs

Common operations

View logs

zdev logs -f                         # all services
zdev logs -f fastify-nova            # one service
zdev logs -f fastify-nova orion-backend  # multiple

Rebuild after code changes

Vite services (seller-panel, orion-frontend) reload automatically via HMR — no rebuild needed. For backend services with a Dockerfile:

zdev up --build fastify-nova        # rebuild and restart
zdev build --no-cache fastify-nova  # rebuild with no cache layer

Open a shell inside a container

zdev exec fastify-nova sh
zdev exec redis sh

Stopping and resetting

zdev down              # stop all containers, keep volumes (data preserved)
zdev down -v           # stop + wipe all volumes (Redis data, ClickHouse data, node_modules)
zdev down -v && zdev build --no-cache && zdev up  # full reset from scratch

Remove only frontend node_modules volumes

Forces a fresh npm install on next start without touching Redis or ClickHouse data:

docker volume rm zelly_seller_panel_nm zelly_orion_frontend_nm

Changing local domain names

Domain names default to *.test but can be overridden in terraform/local-dev/.env:

# terraform/local-dev/.env
LOCAL_NOVA_DOMAIN=api.zelly.local
LOCAL_SELLER_DOMAIN=seller.zelly.local

After changing: update your hosts file and run zdev down && zdev up.