Local Database & Infrastructure Setup

This guide covers setting up the local development infrastructure services (PostgreSQL, Redis, Caddy) using Docker. These services provide the database and caching layer for local development while keeping applications running locally for fast development with hot reloading.

Overview

What Runs Where?

In Docker:

• PostgreSQL (port 5433) - Database server
• Redis (port 6379) - Caching and sessions
• Caddy - Reverse proxy with HTTPS

Locally:

• React webapp (port 3000)
• AdonisJS server (port 3333)
• Next.js marketing (port 8000)

Quick Start

1. Start Infrastructure Services

cd infra/local_dev
docker compose up -d

This starts PostgreSQL, Redis, and Caddy in the background.

2. Set Up HTTPS Certificates

cd infra/local_dev
chmod +x setup-https.sh
./setup-https.sh

This installs mkcert and generates trusted certificates for:

• *.jubiloop.localhost

3. Configure Applications

Since apps run locally but connect to Docker services, configure them to use localhost:

Server (apps/server/.env):

# Database
DB_HOST=localhost
DB_PORT=5433
DB_USER=postgres
DB_PASSWORD=postgres
DB_DATABASE=jubiloop_dev_db

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# Server binding (for Caddy access)
HOST=0.0.0.0
PORT=3333

Web App (apps/webapp/.env):

VITE_API_URL=https://api.jubiloop.localhost
VITE_APP_URL=https://app.jubiloop.localhost

Marketing (apps/marketing/.env):

NEXT_PUBLIC_API_URL=https://api.jubiloop.localhost
NEXT_PUBLIC_APP_URL=https://app.jubiloop.localhost
NEXT_PUBLIC_MARKETING_URL=https://jubiloop.localhost

4. Start Applications

# From project root
npm run dev

5. Access Your Apps

• Web App: https://app.jubiloop.localhost
• API: https://api.jubiloop.localhost
• Marketing: https://jubiloop.localhost

All URLs use HTTPS with trusted certificates.

Service Details

PostgreSQL

• Version: PostgreSQL 15 Alpine
• Port: 5433 (avoids conflicts with local PostgreSQL)
• Credentials:
  • Username: postgres
  • Password: postgres
  • Database: jubiloop_dev_db
• Data: Persisted in Docker volume

Redis

• Version: Redis 7 Alpine
• Port: 6379
• Features:
  • Persistence enabled
  • Data retained across restarts
  • Used for caching and sessions

Caddy

• Purpose: Reverse proxy with automatic HTTPS
• Features:
  • Routes requests to local apps
  • Provides production-like HTTPS
  • Uses mkcert certificates
• Routes:
  • app.jubiloop.localhost → React app (port 3000)
  • api.jubiloop.localhost → AdonisJS (port 3333)
  • jubiloop.localhost → Next.js (port 8000)

Architecture Diagram

┌─────────────────┐    ┌──────────────────┐
│   Your Browser  │───▶│ Caddy (Docker)   │
│                 │    │ :80, :443        │
└─────────────────┘    └──────────┬───────┘
                                  │ host.docker.internal
                       ┌──────────▼───────┐
                       │ Your Local Apps  │
                       │ React :3000      │
                       │ AdonisJS :3333   │
                       │ Next.js :8000    │
                       └──────────┬───────┘
                                  │ localhost
                       ┌──────────▼───────┐
                       │ Docker Services  │
                       │ PostgreSQL :5433 │
                       │ Redis :6379      │
                       └──────────────────┘

Daily Workflow

Starting Your Day

# 1. Start infrastructure (if not running)
cd infra/local_dev && docker compose up -d

# 2. Start applications
npm run dev

# 3. Open your browser
# https://jubiloop.localhost

Database Operations

# Run migrations
npm run migration:run

# Access PostgreSQL directly
docker exec -it jubiloop_local_dev_postgres psql -U postgres -d jubiloop_dev_db

# Use a GUI tool (TablePlus, pgAdmin, etc.)
# Connection: localhost:5433, user: postgres, password: postgres

Redis Operations

# Access Redis CLI
docker exec -it jubiloop_local_dev_redis redis-cli

# Monitor Redis operations
docker exec -it jubiloop_local_dev_redis redis-cli monitor

Common Commands

# View service status
docker compose ps

# View logs
docker compose logs -f
docker compose logs postgres
docker compose logs redis
docker compose logs caddy

# Stop all services
docker compose down

# Reset everything (removes data)
docker compose down -v

# Restart a specific service
docker compose restart postgres

Troubleshooting

Port Conflicts

If you get port binding errors:

# Check what's using ports
lsof -i :5433  # PostgreSQL
lsof -i :6379  # Redis
lsof -i :80    # HTTP
lsof -i :443   # HTTPS

# Solutions:
# 1. Stop conflicting services
# 2. Change ports in docker-compose.yml

Database Connection Issues

1. Check PostgreSQL health:

   docker compose ps
   docker compose logs postgres

2. Test connection:

   psql -h localhost -p 5433 -U postgres -d jubiloop_dev_db

3. Verify .env configuration:

   • Ensure DB_HOST=localhost
   • Ensure DB_PORT=5433

HTTPS Certificate Issues

1. Re-run setup script:

   ./setup-https.sh

2. Restart browser (completely quit and reopen)

3. Check Caddy logs:

   docker compose logs caddy

Apps Can't Connect to Services

1. Verify services are running:

   docker compose ps

2. Check app configuration:

   • Server must bind to 0.0.0.0 (not localhost)
   • Database/Redis must connect to localhost

3. Restart services:

   docker compose restart

Tips & Best Practices

Performance

• Keep Docker Desktop updated
• Allocate sufficient resources to Docker
• Use Docker volumes for data persistence
• Clear unused containers/images periodically

Development

• Use database GUI tools for easier data inspection
• Monitor Redis for caching behavior
• Check Caddy logs for request routing issues
• Use browser DevTools for HTTPS inspection
• Use Git Worktrees for parallel development across branches

Data Management

• Database data persists in Docker volumes
• To reset: docker compose down -v
• To backup: Use pg_dump or GUI tools
• Redis data also persists across restarts