tknuth
/
qrmaster
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
qrmaster/DOCKER_SETUP.md

462 lines
8.8 KiB
Markdown
Raw Permalink Blame History

# 🐳 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! 🎉**
Reference in New Issue View Git Blame Copy Permalink