Docker Development Setup for ERP-Unlocked Monorepo

May contain stale references

This document was audited on 2026-06-22 and contains references that need updating: pdf-api and pdf-worker not in current docker-compose.yml. Cross-check critical details against the current codebase before relying on them.

This document provides comprehensive instructions for Docker-based development in the ERP-Unlocked monorepo, covering both containerized and hybrid development approaches.

Table of Contents

1. Prerequisites
2. Development Environment Setup
3. Docker Compose Development
4. Hybrid Development (Recommended)
5. Building with Docker Bake
6. Individual App Development
7. Database Operations
8. Troubleshooting

Prerequisites

Required Software

• Docker Desktop (4.0+)
• Node.js (18+) with pnpm (8+)
• Python (3.11+) with uv (for Python packages)
• Git for version control

Install pnpm (if not already installed)

npm install -g pnpm@latest

Verify Installation

docker --version
pnpm --version
python --version

Development Environment Setup

1. Clone and Setup Repository

git clone https://github.com/ERP-Unlocked/ordermatic.git
cd ordermatic

# Install all dependencies using pnpm workspaces
pnpm install

# Install Python dependencies for PDF services
cd apps/pdf-api && uv sync && cd ../..
cd apps/pdf-worker && uv sync && cd ../..

2. Environment Configuration

Create environment files for each app:

# Webapp environment
cp apps/webapp/.env.example apps/webapp/.env.local

# PDF API environment
cp apps/pdf-api/.env.example apps/pdf-api/.env

3. Configure Environment Variables

Edit the environment files with your local configuration:

apps/webapp/.env.local:

DATABASE_URL=postgresql://postgres:password@localhost:5432/erp_unlocked
REDIS_URL=redis://localhost:6379
CLERK_SECRET_KEY=your_clerk_secret_key
GEMINI_API_KEY=your_gemini_api_key
PDF_API_URL=http://localhost:8000

apps/pdf-api/.env:

DATABASE_URL=postgresql://postgres:password@localhost:5432/erp_unlocked
REDIS_URL=redis://localhost:6379
GEMINI_API_KEY=your_gemini_api_key
SERVICE_TOKEN=your_service_token

Docker Compose Development

Starting All Services

# Start all services in background
docker-compose up -d

# Start with logs visible
docker-compose up

Service-Specific Commands

# Start only infrastructure services (PostgreSQL, Redis)
docker-compose up -d postgres redis

# Start webapp and its dependencies
docker-compose up webapp postgres redis

# Start PDF processing services
docker-compose up pdf-api pdf-worker redis postgres

Managing Services

# View service status
docker-compose ps

# View logs from all services
docker-compose logs -f

# View logs from specific service
docker-compose logs -f webapp

# Stop all services
docker-compose down

# Stop and remove volumes (clean slate)
docker-compose down -v

Hybrid Development (Recommended)

For optimal development experience, run infrastructure in Docker but apps natively:

1. Start Infrastructure Services

# Start only PostgreSQL and Redis
docker-compose up -d postgres redis

# Verify services are running
docker-compose ps

2. Run Apps Natively

Terminal 1 - Webapp (Astro + React):

cd apps/webapp
pnpm run dev
# → http://localhost:4321

Terminal 3 - PDF API:

cd apps/pdf-api
uv run fastapi dev app/main.py --host 0.0.0.0 --port 8000
# → http://localhost:8000

Terminal 4 - PDF Worker:

cd apps/pdf-worker
uv run celery -A celery_app worker --loglevel=info

3. Database Setup

cd packages/db
pnpm run db:migrate
pnpm run db:seed  # Optional: seed with sample data

Building with Docker Bake

Docker Bake provides unified build configuration for all services:

Build All Services

# Build all Docker services
docker buildx bake

# Build and push to registry (for CI/CD)
docker buildx bake --push

# Build with custom tag
BRANCH_NAME=feature/my-feature COMMIT_SHA=abc123 docker buildx bake

Build Specific Services

# Build only webapp
docker buildx bake webapp

# Build PDF services
docker buildx bake pdf-services

# Build specific service group
docker buildx bake --target pdf-api

Build Configuration

The docker-bake.hcl file defines build targets:

• webapp: Astro customer application
• pdf-api: FastAPI processing service
• pdf-worker: Celery background worker
• Groups: default, webapp, pdf-services

Individual App Development

Webapp (Astro + React)

cd apps/webapp

# Development server
pnpm run dev              # Start dev server on port 4321
pnpm run build            # Build for production
pnpm run preview          # Preview production build

# Database operations
pnpm run db:migrate       # Run database migrations
pnpm run db:studio        # Open Drizzle Studio
pnpm run db:seed          # Seed database with sample data

# Testing and linting
pnpm run test             # Run tests
pnpm run lint             # Lint code
pnpm run type-check       # TypeScript type checking

PDF API (FastAPI)

cd apps/pdf-api

# Development server
uv run fastapi dev app/main.py --host 0.0.0.0 --port 8000

# Production server
uv run gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker

# Testing and utilities
uv run pytest tests/      # Run tests
uv run python -m app.scripts.health_check  # Health check

PDF Worker (Celery)

cd apps/pdf-worker

# Development worker
uv run celery -A celery_app worker --loglevel=info

# Production worker
uv run celery -A celery_app worker --loglevel=warning --concurrency=4

# Monitoring and utilities
uv run celery -A celery_app flower        # Flower web UI
uv run celery -A celery_app status        # Worker status
uv run celery -A celery_app inspect stats # Detailed stats

Database Operations

Using the Database Package

cd packages/db

# Schema operations
pnpm run db:generate      # Generate migration from schema changes
pnpm run db:migrate       # Apply pending migrations
pnpm run db:rollback      # Rollback last migration

# Development utilities
pnpm run db:studio        # Open Drizzle Studio (GUI)
pnpm run db:seed          # Seed with sample data
pnpm run db:reset         # Reset database (drop + migrate + seed)

# Schema validation
pnpm run db:check         # Check for schema drift
pnpm run db:validate      # Validate migration files

Direct Database Access

# Connect to PostgreSQL container
docker exec -it erp_unlocked_postgres psql -U postgres -d erp_unlocked

# Common SQL operations
\dt                       # List tables
\d users                  # Describe table structure
SELECT * FROM users LIMIT 5;  # Query data

Package Development

UI Components

cd packages/ui

# Development
pnpm run dev              # Storybook development server
pnpm run build            # Build component library
pnpm run test             # Test components

# Generate new component
pnpm run generate:component MyComponent

Shared Utils

cd packages/utils

# Development and testing
pnpm run build            # Build TypeScript utilities
pnpm run test             # Run unit tests
pnpm run type-check       # TypeScript validation

Development Workflows

Full Stack Development

1. Start infrastructure: docker-compose up -d postgres redis
2. Run database migrations: cd packages/db && pnpm run db:migrate
3. Start webapp: cd apps/webapp && pnpm run dev
4. Start PDF services: cd apps/pdf-api && uv run fastapi dev app/main.py
5. Start worker: cd apps/pdf-worker && uv run celery -A celery_app worker --loglevel=info

Frontend-Only Development

1. Start infrastructure: docker-compose up -d postgres redis
2. Seed database: cd packages/db && pnpm run db:seed
3. Start webapp: cd apps/webapp && pnpm run dev

API-Only Development

1. Start infrastructure: docker-compose up -d postgres redis
2. Start PDF API: cd apps/pdf-api && uv run fastapi dev app/main.py
3. Start worker: cd apps/pdf-worker && uv run celery -A celery_app worker --loglevel=info

Testing and Quality

Running Tests

# Run all tests from root
pnpm run test

# Run tests for specific app
cd apps/webapp && pnpm run test
cd apps/pdf-api && uv run pytest

# Run specific test suites
pnpm run test:unit        # Unit tests only
pnpm run test:integration # Integration tests only
pnpm run test:e2e         # End-to-end tests

Code Quality

# Lint all code
pnpm run lint

# Format all code
pnpm run format

# Type checking
pnpm run type-check

# Pre-commit hooks (automatic)
git commit -m "Your changes"  # Runs lint, format, type-check automatically

Troubleshooting

Common Issues

Port Conflicts

# Check what's using a port
lsof -i :4321             # Check webapp port
lsof -i :8000             # Check PDF API port

# Kill processes using ports
sudo kill -9 $(lsof -ti:4321)

Database Connection Issues

# Verify PostgreSQL is running
docker-compose ps postgres

# Check database connectivity
docker exec -it erp_unlocked_postgres pg_isready

# Reset database connection
docker-compose restart postgres

pnpm Workspace Issues

# Clear all node_modules and reinstall
pnpm clean               # Custom script to clean all node_modules
pnpm install

# Clear pnpm cache
pnpm store prune

Docker Build Issues

# Clean Docker cache
docker system prune -a

# Rebuild without cache
docker buildx bake --no-cache

# Check Docker Bake configuration
docker buildx bake --print

Debug Commands

Service Health Checks

# Check webapp health
curl http://localhost:4321/health

# Check PDF API health
curl http://localhost:8000/health

# Check Redis connectivity
redis-cli -h localhost -p 6379 ping

# Check PostgreSQL connectivity
docker exec erp_unlocked_postgres pg_isready

Service Logs

# Application logs
docker-compose logs webapp
docker-compose logs pdf-api

# Database logs
docker-compose logs postgres

# Redis logs
docker-compose logs redis

Performance Optimization

Development Performance

# Use pnpm's node_modules linking for faster installs
pnpm config set store-dir ~/.pnpm-store

# Enable pnpm's shamefully-hoist for faster builds
echo "shamefully-hoist=true" >> .npmrc

# Use Docker BuildKit for faster builds
export DOCKER_BUILDKIT=1

Resource Management

# Monitor Docker resource usage
docker stats

# Limit container resources in docker-compose.yml
services:
  webapp:
    deploy:
      resources:
        limits:
          memory: 512M
        reservations:
          memory: 256M

This comprehensive setup ensures efficient development across the entire ERP-Unlocked monorepo, supporting both full containerized development and hybrid approaches based on your preferences and requirements.

Production Deployment Notes

The production deployment process differs significantly from local development:

• PR-Based Workflow: All deployments use strict branch protection with conventional commit formats
• GitHub Actions: Automated builds triggered by pushes to protected branches (main/staging)
• Coolify Integration: Uses webhooks (not direct git integration) to trigger deployments from GHCR images
• Image Registry: All production images stored in GitHub Container Registry with commit-based tagging
• Trigger.dev Integration: Background jobs deployed separately via pnpm run trigger:deploy

For complete deployment procedures, see Deployment Guide.