Skip to content

DOCKER_README.md

Latest commit

 

History

History
258 lines (212 loc) · 7.63 KB

DOCKER_README.md

File metadata and controls

258 lines (212 loc) · 7.63 KB

🐳 Docker Deployment - Complete Setup

📦 What's Included

Your PulsePlay application now has a complete Docker deployment setup with 16 files created:

Configuration Files (11)

  • ✅ Dockerfile - Production build
  • ✅ Dockerfile.dev - Development build with hot reload
  • ✅ Dockerfile.frontend - Frontend-only build
  • ✅ docker-compose.yml - Production orchestration
  • ✅ docker-compose.dev.yml - Development orchestration
  • ✅ docker-compose.atlas.yml - MongoDB Atlas production
  • ✅ .dockerignore - Build optimization
  • ✅ nginx.conf - Web server configuration
  • ✅ .env.docker.template - Environment template
  • ✅ Makefile - Command shortcuts
  • ✅ .github/workflows/docker-deploy.yml - CI/CD pipeline

Documentation (4)

  • ✅ DOCKER_DEPLOYMENT.md - Complete deployment guide
  • ✅ DOCKER_QUICK_REFERENCE.md - Quick reference
  • ✅ DOCKER_FILES_SUMMARY.md - This summary
  • ✅ DOCKER_GITHUB_ACTIONS_DEPLOYMENT.md - CI/CD documentation

🚀 Getting Started (3 Steps)

Step 1: Configure Environment

cp .env.docker.template .env
nano .env  # Edit with your credentials

Step 2: Start Services

make up
# or: docker-compose up -d

Step 3: Access Application

⚙️ Required Configuration

Edit .env with these required values:

# MongoDB
MONGO_ROOT_PASSWORD=your_secure_password_here

# Auth0 (get from https://manage.auth0.com/)
AUTH0_DOMAIN=your-domain.auth0.com
AUTH0_CLIENT_ID=your_client_id
AUTH0_CLIENT_SECRET=your_client_secret

# Google Gemini (get from https://makersuite.google.com/)
GEMINI_API_KEY=your_gemini_api_key

🎯 Common Commands

make help          # Show all available commands
make up            # Start all services (local MongoDB)
make up-atlas      # Start services with MongoDB Atlas
make up-dev        # Start development environment with hot reload
make down          # Stop all services
make down-dev      # Stop development services
make down-atlas    # Stop Atlas services
make logs          # View all logs
make logs-dev      # View development logs
make logs-atlas    # View Atlas deployment logs
make restart       # Restart all services
make health        # Check service health
make backup        # Backup MongoDB
make restore       # Restore from backup
make shell-backend # Access backend container shell
make rebuild       # Rebuild and restart services
make rebuild-dev   # Rebuild development services
make rebuild-atlas # Rebuild Atlas services

🏗️ Architecture Overview

┌─────────────────────────────────────────┐
│           Client Browser                │
│       http://localhost:5173             │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│        Nginx Container (Port 5173)      │
│  • Serves static React frontend         │
│  • Reverse proxy for /api/* requests    │
│  • WebSocket support for real-time      │
│  • Gzip compression & security headers  │
└──────────────┬──────────────────────────┘
               │
               │ /api/* → backend:3000
               ▼
┌─────────────────────────────────────────┐
│      Backend Container (Port 3000)      │
│  • Express.js REST API (TypeScript)     │
│  • MongoDB connection with Mongoose     │
│  • Auth0 JWT authentication             │
│  • Google Gemini AI integration         │
│  • WebSocket server for real-time       │
└──────────────┬──────────────────────────┘
               │
               │ mongodb://mongodb:27017
               ▼
┌─────────────────────────────────────────┐
│      MongoDB Container (Port 27017)     │
│  • Document database with Mongoose ODM  │
│  • User sessions & preferences          │
│  • Audio analysis data storage          │
│  • Persistent volumes & health checks   │
└─────────────────────────────────────────┘

Optional (with --profile debug):
┌─────────────────────────────────────────┐
│   Mongo Express (Port 8081)             │
│  • Web-based database admin interface   │
│  • Query execution & data inspection    │
└─────────────────────────────────────────┘

📊 Services

Service Port Technology Purpose
Frontend (Nginx) 5173 React + TypeScript Serves SPA + proxies API
Backend (Node.js) 3000 Express.js + TypeScript REST API + WebSockets
MongoDB 27017 MongoDB + Mongoose Document database
Mongo Express 8081 Web UI Database admin (optional)

🔐 Security Features

  • ✅ Multi-stage Docker builds
  • ✅ Non-root containers
  • ✅ Environment variable isolation
  • ✅ Network isolation
  • ✅ Health checks
  • ✅ Security headers (Nginx)
  • ✅ CORS configuration

🌐 Deployment Options

Local Development

# With hot reload
docker-compose -f docker-compose.dev.yml up

# Or without Docker
npm run dev:all

Production

# Using Make
make up

# Or docker-compose
docker-compose up -d

Cloud Platforms

  • AWS: ECS, Fargate, EC2
  • Google Cloud: Cloud Run, GKE
  • DigitalOcean: App Platform
  • Azure: Container Instances
  • Heroku: Container Registry

📚 Documentation

  1. DOCKER_DEPLOYMENT.md

    • Complete deployment guide
    • Production best practices
    • Troubleshooting
    • Monitoring setup

  2. DOCKER_QUICK_REFERENCE.md

    • Quick command reference
    • Common operations
    • Troubleshooting tips

  3. DOCKER_FILES_SUMMARY.md

    • File descriptions
    • Architecture details
    • Next steps

  4. Makefile

    • Run make help for all commands

🐛 Troubleshooting

Services won't start

docker-compose logs
docker-compose ps

Port conflicts

# Edit .env
BACKEND_PORT=3001
FRONTEND_PORT=8080

MongoDB issues

docker-compose logs mongodb
docker-compose exec mongodb mongosh

Rebuild after changes

make rebuild

✨ Features

Production Ready

  • ✅ Optimized builds
  • ✅ Health checks
  • ✅ Automatic restarts
  • ✅ Persistent volumes
  • ✅ Logging
  • ✅ Backup/restore

Development Friendly

  • ✅ Hot reload
  • ✅ Debug ports
  • ✅ Database UI
  • ✅ Easy commands

CI/CD Pipeline

  • ✅ Automated builds
  • ✅ Security scanning
  • ✅ Multi-platform support
  • ✅ GitHub Container Registry

📞 Need Help?

Status: ✅ Ready for deployment
Created: October 19, 2025
Docker: 20.10+ required
Compose: 2.0+ required