Skip to content

Docker Setup

This guide will help you set up AccessALI using Docker, the recommended approach for development.

Why Docker?

  • 5-minute setup - Get started quickly
  • Consistent environment - Same setup across all team members
  • Production parity - Develop in an environment similar to production
  • No local dependencies - PostgreSQL and Redis run in containers
  • Easy cleanup - Remove everything with one command

Prerequisites

Before you begin, ensure you have:

Installation Steps

1. Clone the Repository

git clone https://github.com/stratpoint-engineering/poc-access-ali.git
cd poc-access-ali

2. Copy Environment File

cp .env.docker .env

The .env.docker file contains pre-configured environment variables for Docker development.

3. Build and Start Services

cd src
pnpm docker:dev:build

This command will:

  • Build the Next.js application Docker image
  • Start PostgreSQL container
  • Start Redis container
  • Start the application container with hot-reload
  • Set up networking between containers

Expected output: 

[+] Building 45.2s (18/18) FINISHED
[+] Running 4/4
 ✔ Network accessali_default        Created
 ✔ Container accessali-postgres     Started
 ✔ Container accessali-redis        Started
 ✔ Container accessali-app          Started

4. Run Database Migrations

In a new terminal window:

cd src
pnpm docker:db:migrate

This will:

  • Create database tables
  • Set up relationships
  • Apply all migrations

5. Seed the Database (Optional)

pnpm docker:db:seed

This populates the database with sample data for development.

6. Verify Installation

Open your browser and navigate to:

You should see the AccessALI login page.

7. View Database (Optional)

Start Prisma Studio to view and edit database records:

pnpm docker:db:studio

Access Prisma Studio at http://localhost:5555

Docker Architecture

graph TB
    subgraph "Docker Network"
        A[accessali-app<br/>Port 3000]
        B[accessali-postgres<br/>Port 5432]
        C[accessali-redis<br/>Port 6379]
        D[prisma-studio<br/>Port 5555]
    end

    A --> B
    A --> C
    D --> B

    E[Your Browser] --> |localhost:3000| A
    E --> |localhost:5555| D

Container Details

Application Container

  • Image: accessali-app:dev
  • Port: 3000

  • Features:

    • Hot-reload enabled
    • Volume-mounted source code
    • Runs as non-root user
    • Auto-restarts on failure

PostgreSQL Container

  • Image: postgres:16-alpine
  • Port: 5432
  • Database: accessali_dev
  • User: accessali

  • Features:

    • Persistent data volume
    • Optimized configuration
    • Health checks

Redis Container

  • Image: redis:7-alpine
  • Port: 6379

  • Features:

    • Persistent data volume
    • Memory optimized
    • Health checks

Common Docker Commands

Daily Development

# Start all services
pnpm docker:dev

# Start in background (detached mode)
pnpm docker:dev:detach

# View logs (all services)
pnpm docker:logs

# View application logs only
pnpm docker:logs:app

# Stop all services
pnpm docker:down

# Restart services
pnpm docker:restart

Database Operations

# Run migrations
pnpm docker:db:migrate

# Seed database
pnpm docker:db:seed

# Open Prisma Studio
pnpm docker:db:studio

# Reset database (WARNING: Deletes all data)
pnpm docker:db:reset

Container Management

# List running containers
pnpm docker:ps

# Access application container shell
pnpm docker:shell

# View container resource usage
docker stats

Cleanup

# Stop containers (keep data)
pnpm docker:down

# Stop and remove volumes (delete data)
pnpm docker:down:volumes

# Complete cleanup (remove everything)
pnpm docker:clean

Environment Variables

The .env.docker file contains:

# Database
DATABASE_URL="postgresql://accessali:password@accessali-postgres:5432/accessali_dev"

# Redis (optional)
REDIS_URL="redis://accessali-redis:6379"

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

# Mock APIs (use mocks during development)
USE_MOCK_SAP="true"
USE_MOCK_SALESFORCE="true"
USE_MOCK_SPRINGCM="true"
USE_MOCK_ELEDGER="true"

Production Secrets

The .env.docker file contains development secrets. Never use these in production!

Troubleshooting

Port Already in Use

Problem: "Error: address already in use"

Solution: 

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or change port in docker-compose.yml

Database Connection Failed

Problem: "Can't connect to database"

Solution: 

# Check container status
docker ps

# View database logs
docker logs accessali-postgres

# Restart database container
docker restart accessali-postgres

# Check connection from app container
pnpm docker:shell
psql $DATABASE_URL

Container Won't Start

Problem: "Container exits immediately"

Solution: 

# View logs for errors
pnpm docker:logs:app

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

Out of Disk Space

Problem: "No space left on device"

Solution: 

# Clean up Docker resources
docker system prune -a --volumes

# Or use pnpm script
pnpm docker:clean

Hot-Reload Not Working

Problem: "Changes not reflected in browser"

Solution:

  1. Check that source code is mounted: 

    docker inspect accessali-app | grep Mounts -A 20

  2. Restart the container: 

    pnpm docker:restart

  3. Hard refresh browser (Cmd+Shift+R or Ctrl+Shift+R)

Development Workflow

Daily Routine

# Morning - Start services
pnpm docker:dev

# During development
# - Edit code in your editor
# - Browser auto-reloads
# - Check logs if needed: pnpm docker:logs:app

# End of day - Stop services
pnpm docker:down

Making Database Changes

# 1. Edit prisma/schema.prisma

# 2. Generate migration
pnpm docker:db:migrate

# 3. View changes in Prisma Studio
pnpm docker:db:studio

Debugging

# Access container shell
pnpm docker:shell

# Run commands inside container
pnpm type-check
pnpm lint
pnpm test

# Exit shell
exit

Performance Tips

macOS Performance

Docker on macOS can be slow due to file system overhead. Improve performance:

  1. Increase Docker resources:

    • Open Docker Desktop
    • Go to Settings → Resources
    • Increase CPU to 4+ cores
    • Increase Memory to 8+ GB

  2. Use volume delegation (already configured): 

    volumes:
  - ./src:/app:delegated  # Improves macOS performance

  3. Exclude node_modules from mounting: 

    volumes:
  - ./src:/app:delegated
  - /app/node_modules  # Use container's node_modules

Windows Performance

Use WSL 2 for better performance:

  1. Ensure WSL 2 is enabled
  2. Clone repository inside WSL 2 filesystem (/home/user/...)
  3. Run Docker commands from WSL 2 terminal

Next Steps

Additional Resources