scoffer/DOCKER_SETUP.md

Docker Setup for Recipe Management App

Full Stack Containerized Setup

This project includes a complete Docker Compose setup that orchestrates the entire application stack:

• Frontend: React TypeScript application with Nginx
• Backend: Node.js Express API
• Database: MongoDB with persistent storage
• Admin Interface: Mongo Express for database management

Quick Start

1. Create environment file:

   cp env.example .env
   

   Edit the .env file with your desired credentials.

2. Start all services:

   docker-compose up -d
   

3. Access the application:

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:5000
   • Mongo Express: http://localhost:8081

Environment Configuration

Create a .env file in the project root with the following variables:

# MongoDB Configuration
MONGODB_USERNAME=admin
MONGODB_PASSWORD=password123
MONGODB_DATABASE=recipe-management

# JWT Secret for Backend Authentication
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production

Services Architecture

Frontend Service

• Container: recipe-management-frontend
• Port: 3000 (mapped to container port 80)
• Technology: React TypeScript with Nginx
• Features:
  • Production-optimized build
  • API proxy to backend
  • Gzip compression
  • Security headers

Backend Service

• Container: recipe-management-backend
• Port: 5000
• Technology: Node.js Express
• Features:
  • Health checks
  • Environment-based configuration
  • Automatic MongoDB connection
  • Non-root user security

MongoDB Service

• Container: recipe-management-mongodb
• Port: 27017
• Features:
  • Persistent data volume
  • Health checks
  • Automatic seed data loading
  • Authentication enabled

Mongo Express Service

• Container: recipe-management-mongo-express
• Port: 8081
• Features:
  • Web-based MongoDB administration
  • Connected to main MongoDB instance

Development Workflow

Building and Running

# Build and start all services
docker-compose up -d --build

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

# Stop and remove volumes (WARNING: This deletes data)
docker-compose down -v

Individual Service Management

# Restart specific service
docker-compose restart backend

# View logs for specific service
docker-compose logs -f frontend

# Execute commands in running container
docker-compose exec backend sh

Data Persistence

• MongoDB Data: Stored in mongodb_data Docker volume
• Seed Data: Automatically loaded from backend/seedData.js on first startup
• Persistent Storage: Data survives container restarts and rebuilds

Network Architecture

All services communicate through a dedicated Docker network (recipe-network):

• Frontend → Backend: Internal container communication
• Backend → MongoDB: Internal container communication
• External access via mapped ports only

Security Features

• Non-root containers: All services run as non-privileged users
• Environment-based secrets: Credentials managed via environment variables
• Network isolation: Services communicate only through defined network
• Health checks: Automatic service health monitoring
• Security headers: Frontend served with security headers via Nginx

Troubleshooting

Common Issues

1. Port conflicts: Ensure ports 3000, 5000, 8081, 27017 are available
2. Environment variables: Check .env file exists and has correct values
3. Build failures: Run docker-compose build --no-cache to rebuild from scratch

Useful Commands

# Check service status
docker-compose ps

# View resource usage
docker stats

# Clean up unused Docker resources
docker system prune -f