Complete setup instructions for the Event Manager — from quick demo mode to full production deployment
This guide provides comprehensive instructions for setting up the Event Manager from scratch. Whether you are exploring the codebase or deploying to production, this guide covers all scenarios.
Choose the setup path that matches your needs:
| Goal | What You Need | Time | Guide Section |
|---|---|---|---|
| Explore the UI | Bun only | 2 min | Frontend Demo Mode |
| Full development | Bun + Docker | 10 min | Full Development Setup |
| Production deployment | Docker + Cloud DB | 30 min | Production Setup |
┌─────────────────────────────────────────────────────────────────────────────┐
│ DEPENDENCY REQUIREMENTS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ FRONTEND (Demo Mode) │
│ └── Bun ────────────────────────────────────────────────────── REQUIRED │
│ └── shared-types (built) ───────────────────────────────────── REQUIRED │
│ │
│ FRONTEND (Normal Mode) │
│ └── Everything above ───────────────────────────────────────── REQUIRED │
│ └── Backend running ────────────────────────────────────────── REQUIRED │
│ └── OPENROUTER_API_KEY ─────────────────────────────────────── For AI │
│ │
│ BACKEND │
│ └── Bun ────────────────────────────────────────────────────── REQUIRED │
│ └── PostgreSQL ─────────────────────────────────────────────── REQUIRED │
│ └── Redis ──────────────────────────────────────────────────── REQUIRED │
│ └── DATABASE_URL env var ───────────────────────────────────── REQUIRED │
│ └── REDIS_URL env var ──────────────────────────────────────── REQUIRED │
│ └── COOKIE_SECRET env var ──────────────────────────────────── REQUIRED │
| Missing Dependency | Component | Behavior |
|---|---|---|
| PostgreSQL | Backend | Crashes on startup with "DATABASE_URL is required" |
| Redis | Backend | Starts but real-time features fail, jobs don't run |
COOKIE_SECRET | Backend | Crashes on startup |
OPENROUTER_API_KEY | Both | AI chat disabled, everything else works |
| WhatsApp API keys | Backend | Can't send/receive WhatsApp messages |
| Messenger API keys | Backend | Can't send/receive Messenger messages |
| Backend | Frontend | 503 errors on all API calls (use Demo Mode instead) |
shared-types built | Both | TypeScript compilation errors |
| Tool | Version | Installation |
|---|---|---|
| Bun | 1.x+ | curl -fsSL https://bun.sh/install | bash |
| Git | Any | git-scm.com |
| Tool | Version | Purpose |
|---|---|---|
| Docker | 20.x+ | PostgreSQL, Redis containers |
| Docker Compose | 2.x+ | Container orchestration |
| Tool | Purpose |
|---|---|
| ngrok | Expose local server for WhatsApp/Messenger webhooks |
| VS Code/Cursor | Recommended IDE with TypeScript support |
Demo mode allows you to explore the entire frontend UI with mock data. Perfect for evaluating the application before full setup, UI/UX development without infrastructure, and quick demonstrations. See the dedicated Demo Mode page for full details.
git clone https://github.com/your-repo/event-manager.git
cd event-managerbun installThis setup runs the complete application stack locally.
git clone https://github.com/your-repo/event-manager.git
cd event-manager
bun installcp env.example .env| Variable | Description | Example |
|---|---|---|
DATABASE_URL | PostgreSQL connection string | postgresql://user:pass@host:5432/db |
REDIS_URL | Redis connection string | redis://localhost:6379 |
COOKIE_SECRET | Secret for signing cookies | Random 32+ char string |
BETTER_AUTH_SECRET | Secret for authentication | Random 32+ char string |
| Variable | Description | Default |
|---|---|---|
NEXT_PUBLIC_DEMO_MODE | Enable demo mode | false |
NEXT_PUBLIC_BACKEND_URL | Backend API URL | http://localhost:4000 |
NEXT_PUBLIC_WS_URL | WebSocket URL | -- |
NEXT_PUBLIC_APP_URL | Public app URL | http://localhost:3000 |
| Variable | Description | Required For |
|---|---|---|
OPENROUTER_API_KEY | OpenRouter API key | AI chat features |
OPENROUTER_BASE_URL | OpenRouter base URL | Custom endpoints |
| Variable | Description | How to Get |
|---|---|---|
PHONE_NUMBER_ID | WhatsApp Business phone ID | Meta Developer Console |
ACCESS_TOKEN | WhatsApp API access token | Meta Developer Console |
WABA_ID | WhatsApp Business Account ID | Meta Developer Console |
APP_ID | Meta App ID | Meta Developer Console |
APP_SECRET | Meta App Secret | Meta Developer Console |
WHATSAPP_WEBHOOK_VERIFY_TOKEN | Webhook verification token | You create this |
| Variable | Description | How to Get |
|---|---|---|
MESSENGER_PAGE_ACCESS_TOKEN | Facebook Page access token | Meta Developer Console |
MESSENGER_APP_SECRET | Meta App secret for signature verification | Meta Developer Console |
MESSENGER_VERIFY_TOKEN | Webhook verification token | You create this |
MESSENGER_PAGE_ID | Facebook Page ID | Facebook Page Settings |
| Variable | Description | Default |
|---|---|---|
PORT | Backend HTTP port | 4000 |
REALTIME_PORT | WebSocket port | 9100 |
LOG_LEVEL | Logging verbosity | info |
TIMEZONE | Business timezone | America/New_York |
DISCORD_WEBHOOK_URL | Alert notifications URL | -- |
S3_BUCKET | Backup storage bucket | -- |
Cause: Missing or invalid DATABASE_URL in .env
# Ensure PostgreSQL is running
docker-compose up -d postgres
# Add to .env
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/event_managerCause: Missing REDIS_URL in .env
# Ensure Redis is running
docker-compose up -d redis
# Add to .env
REDIS_URL=redis://localhost:6379Cause: Backend or database not running
# Check what's running
docker-compose ps
# Start missing services
docker-compose up -d postgres redis
# Wait and check logs
docker-compose logs -fCause: Database schema not synchronized
cd server
bun run prisma:generate
bun run prisma:db:pushCause: Shared types package not built
bun --filter ./shared-types buildCause: Another process using port 3000 or 4000
# Find process using port
lsof -i :3000 # or :4000
# Kill it
kill -9 <PID>
# Or use different ports
PORT=4001 bun run dev:server# Check PostgreSQL
docker exec event_postgres pg_isready -U postgres
# Check Redis
docker exec event_redis redis-cli ping
# Check backend
curl http://localhost:4000/health
# Check frontend
curl http://localhost:3000┌─────────────────────────────────────────────────────────────────┐
│ FRONTEND │
│ Next.js 16 + React 19 + TanStack Query + Tailwind CSS │
│ Port: 3000 │
├─────────────────────────────────────────────────────────────────┤
│ │ │
│ HTTP/REST │
│ ▼ │
├─────────────────────────────────────────────────────────────────┤
│ BACKEND │
│ NestJS 11 + Bun + Clean Architecture + CQRS │
│ Port: 4000 (HTTP) + 9100 (WebSocket) │
├─────────────────────────────────────────────────────────────────┤
│ │ │ │
│ PostgreSQL Redis │
│ Port: 5432 Port: 6379 │
│ (Data + Sessions) (Cache + Pub/Sub + Jobs) │
└─────────────────────────────────────────────────────────────────┘event-manager/
├── frontend/ # Next.js application
│ ├── app/ # App Router pages
│ ├── src/ # Source code (FSD architecture)
│ └── .env.local # Frontend environment
├── server/ # NestJS backend
│ ├── src/ # Source code (Clean Architecture)
│ ├── prisma/ # Database schema
│ └── .env # Backend environment
├── shared-types/ # Shared TypeScript types
├── docker-compose.yml # Infrastructure config
└── .env # Root environment (used by Docker)For production deployment, additional considerations apply.
COOKIE_SECRET and BETTER_AUTH_SECRETNODE_ENV=productionTRUSTED_ORIGINS for CORSNODE_ENV=production
DATABASE_URL=postgresql://user:password@prod-db-host:5432/event_manager
REDIS_URL=redis://:password@prod-redis-host:6379
COOKIE_SECRET=<generated-64-char-random-string>
BETTER_AUTH_SECRET=<generated-64-char-random-string>
BETTER_AUTH_URL=https://your-domain.com
NEXT_PUBLIC_APP_URL=https://your-domain.com
TRUSTED_ORIGINS=https://your-domain.com# Build and run production containers
docker-compose -f docker-compose.prod.yml up -d
# View logs
docker-compose -f docker-compose.prod.yml logs -fA debug page is available at /debug for developers. It displays diagnostic information about the application state, including connection status, environment details, and real-time event logs. This page is intended for development and troubleshooting, not for end users.
After completing setup:
The shared types package must be compiled before the frontend can resolve its TypeScript types.
bun --filter ./shared-types buildcd frontend
echo "NEXT_PUBLIC_DEMO_MODE=true" >> .env.localAdd the minimum required variables for local development to your .env file:
# Core (REQUIRED)
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/event_manager
REDIS_URL=redis://localhost:6379
COOKIE_SECRET=your-random-secret-string-here
# Auth (REQUIRED for login)
BETTER_AUTH_SECRET=another-random-secret-string
BETTER_AUTH_URL=http://localhost:3000
# Optional but recommended
OPENROUTER_API_KEY=your-openrouter-key # For AI chat features# Start PostgreSQL and Redis containers
docker-compose up -d postgres redis
# Verify containers are running
docker-compose ps
# Wait for PostgreSQL to be ready (check logs)
docker-compose logs -f postgres
# Look for: "database system is ready to accept connections"
# Press Ctrl+C to exit logs# Build shared types first
bun --filter ./shared-types build
# Generate Prisma client
cd server
bun run prisma:generate
# Push schema to database (creates tables)
bun run prisma:db:push
# Return to project root
cd ..Terminal 1 -- Backend:
bun run dev:server
# Expected output:
# Server ready: http://localhost:4000Terminal 2 -- Frontend:
bun run dev
# Expected output:
# Next.js 16.x
# - Local: http://localhost:3000To make a user admin:
# Connect to PostgreSQL
docker exec -it event_postgres psql -U postgres -d event_manager
# Update user role
UPDATE "User" SET role = 'ADMIN' WHERE email = 'your@email.com';