Docker Setup Checklist — Local Development

Work through this top to bottom. Every step is required.

#Prerequisites

• Docker Desktop installed (Mac/Windows) or Docker Engine (Linux)
• Docker version 24+ (docker --version)
• Docker Compose v2 (docker compose version)
• Node.js 20+ installed locally (for running CLI tools outside container)
• VS Code with Docker extension installed (optional but useful)
• Portainer will be available at localhost:9000 for visual container management

#Step 1 — Clone & Setup

• Clone the repository
• Navigate to payday-backend/
• Copy environment file: cp .env.example .env
• Open .env and fill in the following required fields:
  • DB_PASSWORD — choose any strong password
  • REDIS_PASSWORD — choose any strong password
  • JWT_ACCESS_SECRET — generate: openssl rand -hex 32
  • JWT_REFRESH_SECRET — generate: openssl rand -hex 32 (different from above)
  • COOKIE_SECRET — generate: openssl rand -hex 16

#Step 2 — Start All Containers

docker compose up -d

Expected output: 6 containers starting. Wait ~30 seconds for full health.

• All 6 containers show running status: docker compose ps
• Postgres health: docker compose exec postgres pg_isready -U payday_user
• Redis health: docker compose exec redis redis-cli -a $REDIS_PASSWORD ping → PONG

#Step 3 — Verify API

• API responds: curl http://localhost/health Expected: { "status": "ok", "info": { "database": {...}, "redis": {...} } }
• Swagger docs load: open http://localhost/docs in browser
• API root: curl http://localhost/api/v1/ returns platform info

#Step 4 — Verify Database

• Tables created: docker compose exec postgres psql -U payday_user -d payday_db -c "\dt" You should see ~18 tables listed
• pgvector loaded: docker compose exec postgres psql -U payday_user -d payday_db -c "SELECT * FROM pg_extension WHERE extname='vector';"
• Seed data present: docker compose exec postgres psql -U payday_user -d payday_db -c "SELECT email FROM users;" Should show 5 users (admin + 4 test members)

#Step 5 — Verify Redis

• Connect: docker compose exec redis redis-cli -a $REDIS_PASSWORD
• Ping: PING → PONG
• Check databases: INFO keyspace

#Step 6 — Verify Email (Mailhog)

• Mailhog UI accessible: open http://localhost:8025
• Test send: curl -X POST http://localhost/api/v1/auth/register -H "Content-Type: application/json" -d '{"email":"test@example.com","password":"TestPass123!","displayName":"Test User"}'
• Check Mailhog at http://localhost:8025 — welcome email should appear

#Step 7 — Verify Portainer

• Open http://localhost:9000
• Create admin account on first visit
• All 6 containers visible and green

#Step 8 — Test Auth Flow

# Register
curl -X POST http://localhost/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@test.com","password":"DevPass123!","displayName":"Dev User"}'

# Login (copy accessToken from response)
curl -X POST http://localhost/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@test.com","password":"DevPass123!"}'

# Get profile (replace TOKEN with actual accessToken)
curl http://localhost/api/v1/auth/me \
  -H "Authorization: Bearer TOKEN"

• Register returns accessToken + refreshToken
• Login returns tokens
• /auth/me returns user + profile data

#Step 9 — Configure OAuth (If Using)

##Google

• Go to Google Cloud Console
• Create project → Enable Google+ API
• Create OAuth 2.0 Client ID (Web application)
• Add authorized redirect: http://localhost/api/v1/auth/google/callback
• Copy GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET to .env
• Restart API: docker compose restart api
• Test: open http://localhost/api/v1/auth/google in browser

##Apple

• Apple requires HTTPS — use ngrok for local testing: ngrok http 80 → copy the HTTPS URL
• Register redirect: https://YOUR-NGROK-URL.ngrok.io/api/v1/auth/apple/callback
• Set APP_URL=https://YOUR-NGROK-URL.ngrok.io in .env
• Fill in APPLE_CLIENT_ID, APPLE_TEAM_ID, APPLE_KEY_ID, APPLE_PRIVATE_KEY

#Step 10 — WebSocket Test

Open browser console on any page and run:

const socket = io('http://localhost', {
  auth: { token: 'YOUR_ACCESS_TOKEN' }
});
socket.on('connect', () => console.log('✅ Socket connected:', socket.id));
socket.on('connect_error', (err) => console.log('❌ Error:', err.message));

• Socket connects successfully (not disconnected)
• No connect_error events

#Useful Development Commands

# Watch API logs (hot reload active)
docker compose logs -f api

# Full reset (delete ALL data and restart fresh)
docker compose down -v && docker compose up -d

# Rebuild API after package.json changes
docker compose build api && docker compose restart api

# Run a database migration (when you add it)
docker compose exec api npm run migration:run

# Open a psql shell
docker compose exec postgres psql -U payday_user -d payday_db

# Open Redis CLI
docker compose exec redis redis-cli -a YOUR_REDIS_PASSWORD

# Execute any nest command inside container
docker compose exec api npx nest g service my-new-service

#Troubleshooting