Development Setup

Active development

Moonlight is in active development. Dependencies, environment variables and the docker-compose layout below match the current state of the repo and are reviewed as the stack evolves. If something here drifts from what you see in the codebase, the codebase wins.

Prerequisites

• Node.js 20+
• Docker & Docker Compose
• npm (backend), pnpm (frontend)

Quick Start

1. Start Infrastructure

docker-compose up

This starts:

• PostgreSQL (port 9432) — main database
• PostgreSQL (port 9433) — test database
• Pub/Sub emulator (port 8085) — Google Cloud Pub/Sub stand-in for ingest, accounting-sync, scheduler-tick topics
• MinIO (ports 9000/9001) — S3-compatible file storage
• Flyway — database migrations (run automatically)

2. Start Backend

cd moonlight-server
cp .env.example .env
npm install
npm run start:dev

Server runs at http://localhost:3000.

API docs available at http://localhost:3000/api/docs.

3. Start Frontend

cd moonlight-ui
cp .env.example .env
pnpm install
pnpm dev

UI runs at http://localhost:5173.

4. Test Login

Email: [email protected]
Password: password123

(These credentials are created by sample/sample-data.sql)

Database

Connection

Parameter	Value
Host	localhost
Port	9432
User	moon
Password	moonpass
Database	moon_db

Migrations

Schema is managed by Flyway. To add a new migration:

# Create a new migration file
touch flyway/migrations/V10__description.sql

# Restart docker-compose to apply
docker-compose down && docker-compose up

Seeding

Load sample data:

psql -h localhost -p 9432 -U moon -d moon_db -f sample/sample-data.sql

Environment Variables

Backend (moonlight-server/.env)

Variable	Default	Description
PORT	3000	Server port
DB_HOST	localhost	Database host
DB_PORT	9432	Database port
DB_USER	moon	Database user
DB_PASS	moonpass	Database password
DB_NAME	moon_db	Database name
JWT_SECRET	—	JWT signing secret
PUBSUB_PROJECT_ID	moonlight-local	Pub/Sub project id (matches docker-compose --project)
PUBSUB_EMULATOR_HOST	localhost:8085	Emulator address; unset in production to talk to real Pub/Sub
PUBSUB_AUTO_CREATE	true	Auto-create topics/subscriptions on app boot (set false in prod when infra is provisioned)
LOCAL_SCHEDULER_ENABLED	(auto)	Enables local scheduler that publishes periodic ticks; defaults to true when emulator is set
S3_ENDPOINT	http://localhost:9000	S3/MinIO endpoint
S3_BUCKET	moonlight	S3 bucket name
S3_ACCESS_KEY	minioadmin	S3 access key
S3_SECRET_KEY	minioadmin	S3 secret key
S3_REGION	us-east-1	S3 region
OPENAI_API_KEY	—	OpenAI key for OCR (optional)

Frontend (moonlight-ui/.env)

Variable	Default	Description
VITE_API_URL	http://localhost:3000	Backend API URL