Backend Local Setup
This guide walks through getting the Express API, PostgreSQL database, Redis, and BullMQ workers running locally.
Prerequisites
| Requirement | Version | Purpose |
|---|---|---|
| Node.js | >= 20 | Runtime |
| npm | >= 9 | Package manager (workspaces) |
| Docker & Docker Compose | Latest | PostgreSQL 16 + Redis 7 |
| Git | Latest | Source control |
Step-by-Step Setup
1. Clone and Install
git clone <repo-url> Pulse
cd Pulse
npm install
This installs dependencies for all workspaces: apps/api, apps/web, and packages/shared.
2. Start Database Services
docker compose up -d
This starts two containers from docker-compose.yml:
| Service | Image | Port | Purpose |
|---|---|---|---|
| PostgreSQL | postgres:16-alpine | 5432 | Primary database (69+ models) |
| Redis | redis:7-alpine | 6379 | BullMQ queues + rate limiting + caching |
Verify Containers
docker compose ps
# Both should show "running" status
3. Configure Environment
cp apps/api/.env.example apps/api/.env
Edit apps/api/.env with the required values:
| Variable | Example Value | Required |
|---|---|---|
DATABASE_URL | postgresql://postgres:postgres@localhost:5432/unipulse | Yes |
REDIS_URL | redis://localhost:6379 | Yes |
JWT_SECRET | your-secret-key-min-32-chars | Yes |
JWT_REFRESH_SECRET | your-refresh-secret-key | Yes |
ENCRYPTION_KEY | 64-char hex string | Yes |
PORT | 3000 | No (default) |
NODE_ENV | development | No (default) |
FRONTEND_URL | http://localhost:5173 | Yes |
GEMINI_API_KEY | Your Google AI API key | For AI features |
FACEBOOK_APP_ID | Your Facebook app ID | For social features |
FACEBOOK_APP_SECRET | Your Facebook app secret | For social features |
TIKTOK_CLIENT_KEY | Your TikTok client key | For social features |
TIKTOK_CLIENT_SECRET | Your TikTok client secret | For social features |
AWS_S3_BUCKET | Your S3 bucket name | For media uploads |
AWS_S3_REGION | us-east-1 | For media uploads |
SMTP_HOST | smtp.gmail.com | For email (OTP, notifications) |
SMTP_PORT | 587 | For email |
See Environment Variables for the complete reference.
4. Run Database Migrations
cd apps/api
npx prisma migrate dev
npx prisma generate
This creates all 69+ database tables and generates the Prisma client.
5. Build the Shared Package
# From root
npm run build --filter=shared
The API imports types and validators from @unipulse/shared, so this must be built before the API can run.
6. Start the API
# From root
npm run dev --filter=api
The API starts on http://localhost:3000. The base path for all routes is /api/v1.
Health Check
Verify the API is running:
curl http://localhost:3000/api/v1/health
Useful Commands
Database
cd apps/api
# Open Prisma Studio (visual DB browser)
npx prisma studio
# Reset database (drops all data, re-runs migrations)
npx prisma migrate reset
# Generate Prisma client after schema changes
npx prisma generate
# Create a new migration
npx prisma migrate dev --name describe_your_change
# View migration status
npx prisma migrate status
Development
# From root - start everything (API + Web + Shared watch)
npm run dev
# Type check all packages
npm run typecheck
# Run tests
npm run test --filter=api
Docker
# View container logs
docker compose logs -f postgres
docker compose logs -f redis
# Stop containers
docker compose down
# Stop and remove volumes (full reset)
docker compose down -v
Common Issues
| Issue | Solution |
|---|---|
ECONNREFUSED on port 5432 | Docker containers not running. Run docker compose up -d |
ECONNREFUSED on port 6379 | Redis container not running. Run docker compose up -d |
| Prisma client errors | Run npx prisma generate in apps/api |
@unipulse/shared not found | Build shared package: npm run build --filter=shared |
| Migration drift | Run npx prisma migrate dev to apply pending migrations |
| Port 3000 already in use | Kill the existing process or set PORT in .env |
Cross-Reference
- Frontend Local Setup -- getting the web app running
- Docker Infrastructure -- container configuration details
- Environment Variables -- complete env reference
- Schema Overview -- database model guide
- Monorepo Structure -- project layout