DOCKER.md

Docker Setup for NextPlacement

This document explains how to use Docker with the NextPlacement monorepo.

Overview

The project contains three Dockerfiles:

• Dockerfile - Root-level Dockerfile for the entire monorepo
• apps/admin/Dockerfile - Specific Dockerfile for the admin application
• apps/student/Dockerfile - Specific Dockerfile for the student application

Quick Start

Using Docker Compose (Recommended)

1. Build and run both applications:

   docker-compose up --build

2. Run in detached mode:

   docker-compose up -d --build

3. Stop the services:

   docker-compose down

Individual Application Builds

Build Admin Application

docker build -f apps/admin/Dockerfile -t nextplacement-admin .
docker run -p 3001:3001 nextplacement-admin

Build Student Application

docker build -f apps/student/Dockerfile -t nextplacement-student .
docker run -p 3000:3000 nextplacement-student

Build Entire Monorepo

docker build -t nextplacement .
docker run -p 3000:3000 nextplacement

Ports

• Student Application: http://localhost:3000
• Admin Application: http://localhost:3001

Environment Variables

Create a .env file in the root directory with your environment variables:

# Database
DATABASE_URL="your-database-url"

# NextAuth
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-secret"

# Other environment variables...

Then uncomment the env_file section in docker-compose.yml:

env_file:
  - .env

Dockerfile Features

Multi-stage Builds

• deps stage: Installs dependencies with optimal caching
• builder stage: Builds the application
• runner stage: Creates the production image

Security

• Runs as non-root user (nextjs)
• Minimal attack surface with Alpine Linux
• Proper file permissions

Performance

• Layer caching optimization
• Standalone Next.js output
• Minimal production image size

Monorepo Support

• Handles workspace dependencies
• Builds shared packages (@workspace/ui, @workspace/db)
• Uses Turbo for efficient builds

Development with Docker

Development Mode

For development, you can mount the source code:

docker run -v $(pwd):/app -p 3000:3000 nextplacement

Hot Reload

To enable hot reload in development:

docker-compose -f docker-compose.dev.yml up

Production Deployment

Environment Variables

Ensure all required environment variables are set:

docker run -e DATABASE_URL="..." -e NEXTAUTH_SECRET="..." -p 3000:3000 nextplacement

Health Checks

The docker-compose configuration includes health checks that verify the applications are running properly.

Scaling

You can scale individual services:

docker-compose up --scale student=3 --scale admin=2

Troubleshooting

Build Issues

1. Clear Docker cache:

   docker system prune -a

2. Rebuild without cache:

   docker-compose build --no-cache

Runtime Issues

1. Check logs:

   docker-compose logs student
   docker-compose logs admin

2. Access container shell:

   docker-compose exec student sh

Port Conflicts

If ports 3000 or 3001 are already in use, modify the docker-compose.yml:

ports:
  - "3002:3000"  # Map to different host port

Best Practices

1. Always use specific image tags in production
2. Set up proper logging and monitoring
3. Use secrets management for sensitive data
4. Implement proper backup strategies
5. Monitor resource usage

Advanced Configuration

Custom Dockerfile

You can create custom Dockerfiles for specific environments:

# Dockerfile.prod
FROM node:22-alpine AS base
# ... production-specific configuration

Docker Compose Overrides

Create docker-compose.override.yml for local development:

version: '3.8'
services:
  student:
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      - NODE_ENV=development

Monitoring

Health Checks

The applications include health check endpoints. Create an API route:

// apps/student/app/api/health/route.ts
export async function GET() {
  return Response.json({ status: 'ok' })
}

Logging

Configure proper logging for production:

docker-compose up --build 2>&1 | tee app.log

Security Considerations

1. Never commit .env files
2. Use Docker secrets for sensitive data
3. Regularly update base images
4. Scan images for vulnerabilities
5. Implement proper network policies

Performance Optimization

1. Use multi-stage builds (already implemented)
2. Optimize layer caching (already implemented)
3. Use .dockerignore (already implemented)
4. Consider using BuildKit
5. Monitor image sizes

Support

For issues related to Docker setup, check:

1. Docker logs
2. Application logs
3. Network connectivity
4. Environment variables
5. File permissions