# 🐳 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**
   ```bash
   git clone <your-repo-url>
   cd QRMASTER
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Set up environment variables**
   ```bash
   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**
   ```bash
   npm run docker:dev
   ```
   This starts PostgreSQL, Redis, and Adminer.

5. **Run database migrations**
   ```bash
   npm run db:migrate
   ```

6. **Seed the database (optional)**
   ```bash
   npm run db:seed
   ```

7. **Start the development server**
   ```bash
   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**
   ```bash
   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**
   ```bash
   npm run docker:prod
   ```

4. **Run migrations inside the container**
   ```bash
   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

```bash
# 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

```bash
# 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

```bash
# 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

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

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

### Viewing Logs

```bash
# All services
docker-compose logs -f

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

### Rebuilding

```bash
# 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

```env
# 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

```env
# OAuth (Google)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

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

# Features
ENABLE_DEMO=false
```

### Generating Secrets

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# View resource usage
docker stats

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

### Database Size

```bash
# 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

```bash
# 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`:

```bash
#!/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

```bash
# 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`:
   ```yaml
   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**:
   ```bash
   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](https://docs.docker.com/)
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
- [Redis Documentation](https://redis.io/documentation)
- [Prisma Documentation](https://www.prisma.io/docs/)
- [Next.js Documentation](https://nextjs.org/docs)

## 🆘 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! 🎉**