Local Development

Local Development

This guide explains how to set up and run applications locally with automatic database setup.

Quick Start

For any project with a backend, use the dev:*:full command:

pnpm dev:chat:full      # Start chat with auth + database setup
pnpm dev:zitare:full    # Start zitare with auth + database setup
pnpm dev:contacts:full  # Start contacts with auth + database setup

These commands automatically:

1. Create the database if it doesn’t exist
2. Push the latest schema (Drizzle db:push)
3. Start the auth service (mana-core-auth)
4. Start the backend and web app with colored output

Available Full Dev Commands

Command	Database	Backend Port	Web Port
pnpm dev:chat:full	chat	3002	5173
pnpm dev:zitare:full	zitare	3007	5177
pnpm dev:contacts:full	contacts	3015	5184
pnpm dev:calendar:full	calendar	3014	5179
pnpm dev:clock:full	clock	3017	5187
pnpm dev:todo:full	todo	3018	5188
pnpm dev:picture:full	picture	3006	5175

Prerequisites

Before running any dev:*:full command:

1. Start Docker infrastructure

   This starts PostgreSQL, Redis, and MinIO:

   pnpm docker:up

2. Generate environment files

   This runs automatically on pnpm install, but you can run manually:

   pnpm setup:env

Database Setup Commands

Individual Service Setup

pnpm setup:db:auth      # Setup mana-core-auth database + schema
pnpm setup:db:chat      # Setup chat database + schema
pnpm setup:db:zitare    # Setup zitare database + schema
pnpm setup:db:contacts  # Setup contacts database + schema
pnpm setup:db:calendar  # Setup calendar database + schema
pnpm setup:db:clock     # Setup clock database + schema
pnpm setup:db:todo      # Setup todo database + schema
pnpm setup:db:picture   # Setup picture database + schema

Setup All Databases

pnpm setup:db           # Creates ALL databases and pushes ALL schemas

This is useful when setting up a fresh environment or after pulling new schema changes.

How It Works

Docker Init Script

On first pnpm docker:up, the PostgreSQL container runs docker/init-db/01-create-databases.sql which creates all databases:

• manacore, chat, zitare, contacts, calendar, clock, todo, manadeck
• storage, mail, moodlit, finance, inventory, techbase, voxel_lava, figgos

Setup Script

The scripts/setup-databases.sh script:

1. Creates database if it doesn’t exist (using psql)
2. Pushes schema using drizzle-kit push --force

The --force flag auto-approves schema changes without interactive prompts.

Apps Without Full Commands

Some apps don’t have backends or don’t use Drizzle:

App	Reason
manacore	No backend (uses other services)
manadeck	Backend exists but no db:push

For these, use the regular dev commands:

pnpm dev:manacore:web
pnpm dev:manadeck:app

Troubleshooting

Database doesn’t exist

If you see database "xxx" does not exist:

Option 1: Setup Script

pnpm setup:db:chat  # or whichever service

Option 2: Manual

PGPASSWORD=devpassword psql -h localhost -U manacore -d postgres -c "CREATE DATABASE chat;"

Schema out of date

If you see errors about missing tables/columns:

# Push the latest schema
pnpm --filter @chat/backend db:push --force

Port already in use

If auth (port 3001) is already running:

# Check what's using the port
lsof -i :3001

# Kill the process if needed
kill <PID>

Fresh Start (Nuclear Option)

To completely reset all databases:

# Stop and remove all containers + volumes
pnpm docker:clean

# Start fresh
pnpm docker:up

# Setup all databases
pnpm setup:db

Adding a New Application

Tip

See the Project Structure guide for the full directory layout.

Step 1: Create Project Structure

apps/newproject/
├── apps/
│   ├── backend/      # NestJS API (if needed)
│   ├── mobile/       # Expo React Native app
│   ├── web/          # SvelteKit web app
│   └── landing/      # Astro marketing page
├── packages/         # Project-specific shared code
├── package.json      # Workspace root
└── CLAUDE.md         # Project documentation

Step 2: Configure Backend Database

If your backend uses Drizzle ORM:

1. Add database to Docker init (docker/init-db/01-create-databases.sql):

   CREATE DATABASE IF NOT EXISTS newproject;
   GRANT ALL PRIVILEGES ON DATABASE newproject TO manacore;

2. Add DATABASE_URL to .env.development:

   NEWPROJECT_DATABASE_URL=postgresql://manacore:devpassword@localhost:5432/newproject

3. Update scripts/generate-env.mjs to generate the backend .env file.

Step 3: Add Package.json Scripts

Add to root package.json:

{
  "scripts": {
    "dev:newproject:full": "./scripts/setup-databases.sh newproject && ./scripts/setup-databases.sh auth && concurrently \"pnpm dev:auth\" \"pnpm dev:newproject:backend\" \"pnpm dev:newproject:web\"",
    "setup:db:newproject": "./scripts/setup-databases.sh newproject"
  }
}

Step 4: Test

pnpm setup:db:newproject
pnpm dev:newproject:full