QR-master/DOCKER_SETUP.md

🐳 Docker Setup Guide for QR Master

Complete guide for setting up and running QR Master with Docker and PostgreSQL.

Prerequisites

• Docker Desktop (Windows/Mac) or Docker Engine (Linux)
• Docker Compose V2
• Git
• Node.js 18+ (for local development)

🚀 Getting Started

Option 1: Development Mode (Recommended for Development)

Run only the database services in Docker and the Next.js app on your host machine:

1. Clone the repository

   git clone <your-repo-url>
   cd QRMASTER
   

2. Install dependencies

   npm install
   

3. Set up environment variables

   cp env.example .env
   

   Edit .env and update the values, especially:

   • NEXTAUTH_SECRET (generate with: openssl rand -base64 32)
   • IP_SALT (generate with: openssl rand -base64 32)

4. Start database services

   npm run docker:dev
   

   This starts PostgreSQL, Redis, and Adminer.

5. Run database migrations

   npm run db:migrate
   

6. Seed the database (optional)

   npm run db:seed
   

7. Start the development server

   npm run dev
   

8. Access the application

   • App: http://localhost:3050
   • Database UI (Adminer): http://localhost:8080
     • System: PostgreSQL
     • Server: db
     • Username: postgres
     • Password: postgres
     • Database: qrmaster

Option 2: Full Production Mode

Run everything in Docker containers:

1. Clone and configure

   git clone <your-repo-url>
   cd QRMASTER
   cp env.example .env
   

2. Update environment variables in .env Make sure to set strong secrets in production!

3. Build and start all services

   npm run docker:prod
   

4. Run migrations inside the container

   docker-compose exec web npx prisma migrate deploy
   

5. Access the application

   • App: http://localhost:3050

📦 What Gets Installed

Services

1. PostgreSQL 16 - Main database

   • Port: 5432
   • Database: qrmaster
   • User: postgres
   • Password: postgres (change in production!)

2. Redis 7 - Caching and rate limiting

   • Port: 6379
   • Max memory: 256MB with LRU eviction
   • Persistence: AOF enabled

3. Next.js App - The QR Master application

   • Port: 3000
   • Built with production optimizations

4. Adminer - Database management UI (dev only)

   • Port: 8080
   • Lightweight alternative to pgAdmin

🗄️ Database Management

Prisma Commands

# Generate Prisma Client
npm run db:generate

# Create a new migration
npm run db:migrate

# Deploy migrations (production)
npm run db:deploy

# Seed the database
npm run db:seed

# Open Prisma Studio
npm run db:studio

Direct PostgreSQL Access

# Connect to PostgreSQL
docker-compose exec db psql -U postgres -d qrmaster

# Backup database
docker-compose exec db pg_dump -U postgres qrmaster > backup_$(date +%Y%m%d).sql

# Restore database
docker-compose exec -T db psql -U postgres qrmaster < backup.sql

🔧 Docker Commands

Starting Services

# Development mode (database only)
npm run docker:dev
# or
docker-compose -f docker-compose.dev.yml up -d

# Production mode (full stack)
npm run docker:prod
# or
docker-compose up -d --build

# Production with database UI
docker-compose --profile dev up -d

Stopping Services

# Stop all services
npm run docker:stop
# or
docker-compose down

# Stop and remove volumes (⚠️ deletes data!)
docker-compose down -v

Viewing Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f web
docker-compose logs -f db
docker-compose logs -f redis

Rebuilding

# Rebuild the web application
docker-compose build web

# Rebuild without cache
docker-compose build --no-cache web

# Rebuild and restart
docker-compose up -d --build web

🌍 Environment Variables

Required Variables

# Database (automatically set for Docker)
DATABASE_URL=postgresql://postgres:postgres@db:5432/qrmaster?schema=public

# NextAuth
NEXTAUTH_URL=http://localhost:3050
NEXTAUTH_SECRET=<generate-with-openssl-rand-base64-32>

# Security
IP_SALT=<generate-with-openssl-rand-base64-32>

Optional Variables

# OAuth (Google)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

# Redis (automatically set for Docker)
REDIS_URL=redis://redis:6379

# Features
ENABLE_DEMO=false

Generating Secrets

# On Linux/Mac
openssl rand -base64 32

# On Windows (PowerShell)
[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 }))

🔍 Health Checks

All services include health checks:

# Check status of all services
docker-compose ps

# Check database health
docker-compose exec db pg_isready -U postgres

# Check Redis health
docker-compose exec redis redis-cli ping

# Check web app health
curl http://localhost:3050

🐛 Troubleshooting

Database Connection Failed

# Check database is running
docker-compose ps db

# Check database logs
docker-compose logs db

# Restart database
docker-compose restart db

# Test connection
docker-compose exec db psql -U postgres -d qrmaster -c "SELECT version();"

Port Already in Use

# Windows - find process using port
netstat -ano | findstr :3050

# Linux/Mac - find process using port
lsof -i :3050

# Kill the process or change the port in docker-compose.yml

Migration Errors

# Reset the database (⚠️ deletes all data!)
docker-compose exec web npx prisma migrate reset

# Or manually
docker-compose down -v
docker-compose up -d db redis
npm run db:migrate

Container Won't Start

# Remove all containers and volumes
docker-compose down -v

# Remove dangling images
docker image prune

# Rebuild from scratch
docker-compose build --no-cache
docker-compose up -d

Prisma Client Not Generated

# Generate Prisma Client
npm run db:generate

# Or in Docker
docker-compose exec web npx prisma generate

🔐 Production Checklist

Before deploying to production:

• Change PostgreSQL password
• Generate strong NEXTAUTH_SECRET
• Generate strong IP_SALT
• Set proper NEXTAUTH_URL (your domain)
• Configure OAuth credentials (if using)
• Set up database backups
• Configure Redis persistence
• Set up monitoring and logging
• Enable HTTPS/SSL
• Review and adjust rate limits
• Set up a reverse proxy (nginx/Traefik)
• Configure firewall rules
• Set up automated database backups

📊 Monitoring

Resource Usage

# View resource usage
docker stats

# View specific container
docker stats qrmaster-web qrmaster-db qrmaster-redis

Database Size

# Check database size
docker-compose exec db psql -U postgres -d qrmaster -c "
SELECT 
    pg_size_pretty(pg_database_size('qrmaster')) as db_size,
    pg_size_pretty(pg_total_relation_size('\"QRCode\"')) as qrcode_table_size;
"

Redis Info

# Get Redis info
docker-compose exec redis redis-cli info

# Get memory usage
docker-compose exec redis redis-cli info memory

🔄 Backup and Recovery

Automated Backups

Create a backup script backup.sh:

#!/bin/bash
BACKUP_DIR="./backups"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# Backup database
docker-compose exec -T db pg_dump -U postgres qrmaster > "$BACKUP_DIR/qrmaster_$TIMESTAMP.sql"

# Backup Redis
docker-compose exec redis redis-cli BGSAVE

echo "Backup completed: $BACKUP_DIR/qrmaster_$TIMESTAMP.sql"

Restore from Backup

# Stop the web service
docker-compose stop web

# Restore database
cat backup_20241013.sql | docker-compose exec -T db psql -U postgres qrmaster

# Restart
docker-compose start web

🚀 Performance Tips

1. Increase PostgreSQL shared buffers (in production): Edit docker-compose.yml:

   db:
     command: postgres -c shared_buffers=256MB -c max_connections=100
   

2. Enable Redis persistence: Already configured with AOF in docker-compose.yml

3. Use connection pooling: Prisma already includes connection pooling

4. Monitor slow queries:

   docker-compose exec db psql -U postgres -d qrmaster -c "
   SELECT query, mean_exec_time, calls 
   FROM pg_stat_statements 
   ORDER BY mean_exec_time DESC 
   LIMIT 10;"
   

📚 Additional Resources

• Docker Documentation
• PostgreSQL Documentation
• Redis Documentation
• Prisma Documentation
• Next.js Documentation

🆘 Getting Help

If you encounter issues:

1. Check the logs: docker-compose logs -f
2. Check service health: docker-compose ps
3. Review this guide
4. Check the docker/README.md for more details

---

Happy coding! 🎉