Docker Development Guide¶

Last Updated: 2025-11-22

Overview¶

AccessALI uses Docker as the primary development environment to ensure consistency across all team members and production parity. This guide covers Docker setup, common commands, and troubleshooting.

Why Docker?

Consistent Environment - Same setup for all developers
Production Parity - Develop in production-like environment
Quick Setup - Get started in < 5 minutes
No Local Dependencies - Everything runs in containers
Easy Cleanup - Remove everything with one command

Quick Start¶

Prerequisites¶

Docker Desktop - Download
pnpm - npm install -g pnpm
Git - For cloning the repository

Initial Setup¶

# 1. Clone repository
git clone https://github.com/stratpoint-engineering/poc-access-ali.git
cd poc-access-ali

# 2. Copy environment file
cp .env.docker .env

# 3. Navigate to source directory
cd src

# 4. Build and start all services
pnpm docker:dev:build

# 5. Run database migrations (in new terminal)
cd src
pnpm docker:db:migrate

# 6. Access application
open http://localhost:3000

Setup Complete

You now have a fully functional development environment with hot-reload enabled!

Docker Architecture¶

graph TB
    subgraph "Docker Network (accessali-network)"
        App[Next.js App<br/>Port 3000]
        DB[(PostgreSQL<br/>Port 5432)]
        Redis[(Redis<br/>Port 6379)]
        Studio[Prisma Studio<br/>Port 5555]
    end

    App --> DB
    App --> Redis
    Studio --> DB

    Developer[Developer Machine] --> App
    Developer --> Studio

Services¶

1. Next.js Application¶

Container Name: access-ali-app Port: 3000 Features: - Hot module reloading - Source code mounted as volume - Node modules cached in Docker volume

Access:

# Application URL
http://localhost:3000

# View logs
pnpm docker:logs:app

# Access shell
pnpm docker:shell

2. PostgreSQL Database¶

Container Name: access-ali-postgres Port: 5432 Version: PostgreSQL 16 Features: - Persistent data volume - Automatic initialization - Optimized for development

Access:

# Database shell
pnpm docker:db:shell

# Prisma Studio (GUI)
pnpm docker:db:studio
# Opens http://localhost:5555

3. Redis Cache¶

Container Name: access-ali-redis Port: 6379 Version: Redis 7 Features: - Session storage - Application caching - Persistent data (optional)

Access:

# Redis CLI
pnpm docker:exec:redis redis-cli

# View all keys
pnpm docker:exec:redis redis-cli KEYS '*'

4. Prisma Studio¶

Container Name: access-ali-prisma-studio Port: 5555 Features: - Visual database browser - Edit data via GUI - View relationships

Access:

# Start Prisma Studio
pnpm docker:db:studio

# Opens http://localhost:5555

Common Commands¶

Starting & Stopping¶

# Start all services
pnpm docker:dev

# Start with build (first time or after changes)
pnpm docker:dev:build

# Stop all services
pnpm docker:down

# Stop and remove volumes (clean slate)
pnpm docker:down:clean

Viewing Logs¶

# All services
pnpm docker:logs

# Specific service
pnpm docker:logs:app
pnpm docker:logs:db
pnpm docker:logs:redis

# Follow logs (real-time)
pnpm docker:logs:app -f

# Last 100 lines
pnpm docker:logs:app --tail=100

Database Operations¶

# Run migrations
pnpm docker:db:migrate

# Create new migration
pnpm docker:db:migrate:create add_new_field

# Seed database
pnpm docker:db:seed

# Reset database (destructive!)
pnpm docker:db:reset

# Prisma Studio (GUI)
pnpm docker:db:studio

# Database shell
pnpm docker:db:shell

Container Management¶

# View running containers
pnpm docker:ps

# Restart specific service
pnpm docker:restart:app
pnpm docker:restart:db
pnpm docker:restart:redis

# Access container shell
pnpm docker:shell

# Execute command in container
pnpm docker:exec:app ls -la

Cleanup¶

# Stop containers
pnpm docker:down

# Stop and remove volumes
pnpm docker:down:clean

# Complete cleanup (nuclear option)
pnpm docker:clean

# Remove dangling images
docker system prune

File Structure¶

accessali/
├── docker/                   # Docker configuration
│   ├── scripts/              # Helper scripts
│   └── postgres/             # PostgreSQL config
├── docker-compose.yml        # Development services
├── docker-compose.prod.yml   # Production services
├── Dockerfile                # Production image
├── Dockerfile.dev            # Development image
├── .env.docker               # Docker environment variables
└── .dockerignore             # Files to exclude from image

Environment Variables¶

Development (.env.docker)¶

# Database
DATABASE_URL="postgresql://postgres:postgres@postgres:5432/accessali?schema=public"
DIRECT_URL="postgresql://postgres:postgres@postgres:5432/accessali?schema=public"

# NextAuth
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="development-secret-change-in-production"

# Mock APIs (Development)
USE_MOCK_SAP="true"
USE_MOCK_SALESFORCE="true"
USE_MOCK_SPRINGCM="true"

# Redis
REDIS_URL="redis://redis:6379"

Production (.env.production)¶

# Database (Neon)
DATABASE_URL="postgresql://user:pass@neon.tech/db?sslmode=require"
DIRECT_URL="postgresql://user:pass@neon.tech/db?sslmode=require"

# NextAuth
NEXTAUTH_URL="https://your-domain.com"
NEXTAUTH_SECRET="strong-random-secret-32-characters"

# Real APIs (Production)
USE_MOCK_SAP="false"
USE_MOCK_SALESFORCE="false"
USE_MOCK_SPRINGCM="false"

SAP_API_URL="https://sap.company.com/api"
SAP_API_KEY="xxx"

# Redis (Upstash)
REDIS_URL="rediss://user:pass@upstash.com:6379"

Troubleshooting¶

Port Already in Use¶

Error: Bind for 0.0.0.0:3000 failed: port is already allocated

Solution:

# Find process using port
lsof -ti:3000

# Kill process
kill -9 $(lsof -ti:3000)

# Restart Docker
pnpm docker:dev

Container Won't Start¶

Error: Container exits immediately

Solution:

# Check logs
pnpm docker:logs:app

# Rebuild containers
pnpm docker:clean
pnpm docker:dev:build

Database Connection Failed¶

Error: Can't reach database server

Solution:

# Check PostgreSQL is running
pnpm docker:ps

# Restart database
pnpm docker:restart:db

# Check connection string
cat .env.docker | grep DATABASE_URL

# Verify database is healthy
pnpm docker:exec:db pg_isready

Hot Reload Not Working¶

Problem: Changes not reflecting in browser

Solution:

# 1. Restart app container
pnpm docker:restart:app

# 2. Clear Next.js cache
pnpm docker:exec:app rm -rf .next

# 3. Rebuild if issue persists
pnpm docker:down
pnpm docker:dev:build

Permission Denied Errors¶

Error: EACCES: permission denied

Solution:

# Fix ownership (macOS/Linux)
sudo chown -R $USER:$USER .

# Fix node_modules permissions
pnpm docker:exec:app chmod -R 755 node_modules

Out of Disk Space¶

Error: No space left on device

Solution:

# Remove unused containers
docker container prune

# Remove unused images
docker image prune -a

# Remove unused volumes
docker volume prune

# Complete cleanup
docker system prune -a --volumes

Best Practices¶

✅ DO¶

Use Docker for all development
Commit docker-compose.yml changes
Keep .env.docker in source control (no secrets)
Run migrations after schema changes
Clean up unused containers regularly
Use named volumes for data persistence

❌ DON'T¶

Commit .env.local or .env.production
Edit files inside containers
Run docker-compose up directly (use pnpm scripts)
Store sensitive data in .env.docker
Ignore docker-compose.yml conflicts
Delete volumes without backup

Performance Tips¶

macOS/Windows Performance¶

Docker on macOS/Windows can be slower due to file system overhead.

Optimize Performance:

# docker-compose.yml
services:
  app:
    volumes:
      # Use delegated consistency for better performance
      - ./src:/app:delegated
      - /app/node_modules  # Don't sync node_modules

Increase Resources:

Open Docker Desktop
Settings → Resources
Increase CPUs to 4+
Increase Memory to 8GB+

Build Cache¶

Use BuildKit for faster builds:

# Enable BuildKit
export DOCKER_BUILDKIT=1

# Build with cache
pnpm docker:dev:build --no-cache

Production Deployment¶

Building Production Image¶

# Build production image
docker build -t accessali:latest -f Dockerfile .

# Run production container
docker run -p 3000:3000 --env-file .env.production accessali:latest

Docker Compose Production¶

# Start production stack
docker-compose -f docker-compose.prod.yml up -d

# View logs
docker-compose -f docker-compose.prod.yml logs -f

# Stop production stack
docker-compose -f docker-compose.prod.yml down

Development Workflow - Daily development process
Project Structure - File organization
Getting Started: Docker Setup - Detailed setup guide

Next Steps¶

Review Development Workflow for daily development
Explore Project Structure for code organization
Check Conventions for coding standards

Docker Development Guide¶

Overview¶

Quick Start¶

Prerequisites¶

Initial Setup¶

Docker Architecture¶

Services¶

1. Next.js Application¶

2. PostgreSQL Database¶

3. Redis Cache¶

4. Prisma Studio¶

Common Commands¶

Starting & Stopping¶

Viewing Logs¶

Database Operations¶

Container Management¶

Cleanup¶

File Structure¶

Environment Variables¶

Development (.env.docker)¶

Production (.env.production)¶

Troubleshooting¶

Port Already in Use¶

Container Won't Start¶

Database Connection Failed¶

Hot Reload Not Working¶

Permission Denied Errors¶

Out of Disk Space¶

Best Practices¶

✅ DO¶

❌ DON'T¶

Performance Tips¶

macOS/Windows Performance¶

Build Cache¶

Production Deployment¶

Building Production Image¶

Docker Compose Production¶

Related Documentation¶

Next Steps¶