ideas-generator/docker/README.md

# 🚀 Ideas Generator 2025 - Docker Deployment

Complete production-ready Docker deployment for the Ideas Generator 2025 application with Azure AD SSO and hybrid authentication.

## 📋 Overview

This Docker setup provides a complete, production-ready deployment including:

- **Frontend**: Vue.js 3 + Vite (served via Nginx)
- **Backend**: Node.js + Express API server
- **Database**: PostgreSQL 15 with persistent storage
- **Proxy**: Nginx reverse proxy with SSL support
- **Authentication**: Hybrid Azure AD SSO + Password authentication
- **Security**: Production-grade security headers and rate limiting

## 🚀 Quick Start

### Prerequisites

- Docker 20.x or higher
- Docker Compose 2.x or higher
- OpenAI API key
- Azure AD tenant access (for SSO)

### One-Command Deployment

```bash
cd docker
./setup.sh
```

The interactive setup script will guide you through:
- Domain and port configuration
- Database setup with secure credentials
- Azure AD integration
- OpenAI API configuration
- SSL/TLS setup
- Security configuration

## 📁 Architecture

```
docker/
├── docker-compose.yml          # Main orchestration file
├── Dockerfile.backend          # Node.js backend container
├── Dockerfile.frontend         # Vue.js + Nginx frontend container
├── setup.sh                    # Interactive deployment wizard
├── nginx/
│   └── nginx.conf.template    # Nginx configuration with variables
├── postgres/
│   └── init.sql               # Database initialization
└── scripts/
    ├── deploy.sh              # Deployment management commands
    └── frontend-entrypoint.sh # Frontend container initialization
```

## 🔧 Services

### Frontend Service (`frontend`)
- **Base**: nginx:alpine
- **Port**: 80 (HTTP), 443 (HTTPS)
- **Features**: 
  - Production Vue.js build
  - Gzip compression
  - Security headers
  - Rate limiting
  - Health checks

### Backend Service (`backend`)
- **Base**: node:18-alpine
- **Port**: 3000 (internal)
- **Features**:
  - Express.js API server
  - PostgreSQL connection
  - Azure AD token validation
  - OpenAI API integration
  - Health monitoring

### Database Service (`database`)
- **Base**: postgres:15-alpine
- **Port**: 5432 (internal)
- **Features**:
  - Persistent data storage
  - Automatic initialization
  - Health checks
  - Backup support

## ⚙️ Configuration

### Environment Variables

The setup script generates a `.env` file with all necessary configuration:

```env
# Basic Configuration
DOMAIN_NAME=your-domain.com
HTTP_PORT=80
HTTPS_PORT=443

# Database
DATABASE_NAME=ideas_gen_prod
DATABASE_USER=ideas_admin
DATABASE_PASSWORD=generated-secure-password

# Security
JWT_SECRET=generated-jwt-secret

# Azure AD
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id

# OpenAI
OPENAI_API_KEY=your-openai-key

# URLs
FRONTEND_URL=https://your-domain.com
BACKEND_URL=https://your-domain.com/api
CORS_ORIGIN=https://your-domain.com
```

### Manual Configuration

If you prefer manual setup, copy the example:

```bash
cp .env.example .env
# Edit .env with your values
```

## 🚀 Deployment Commands

### Using the Management Script

```bash
# Start all services
./scripts/deploy.sh start

# Build and deploy with latest changes
./scripts/deploy.sh build

# View service status
./scripts/deploy.sh status

# View logs
./scripts/deploy.sh logs

# Stop all services
./scripts/deploy.sh stop
```

### Using Docker Compose Directly

```bash
# Start in background
docker-compose up -d

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

# View logs
docker-compose logs -f

# Stop services
docker-compose down
```

## 🔒 Security Features

### Network Security
- Custom isolated Docker network
- Internal service communication
- No exposed database ports

### Web Security
- HTTPS/SSL support
- Security headers (HSTS, CSP, etc.)
- Rate limiting on API endpoints
- CORS protection

### Authentication Security
- Azure AD token validation
- JWT secret generation
- Password hashing with bcrypt
- Role-based access control

### Container Security
- Non-root user execution
- Minimal base images (Alpine Linux)
- Health checks for all services
- Resource limits and constraints

## 📊 Monitoring & Maintenance

### Health Checks

All services include health checks:

```bash
# Check all service health
docker-compose ps

# View detailed health status
docker inspect ideas-gen-backend --format='{{.State.Health.Status}}'
```

### Logs

Access logs for troubleshooting:

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

# Specific service
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f database
```

### Database Backup

```bash
# Create backup
./scripts/deploy.sh backup

# Manual backup
docker-compose exec database pg_dump -U ideas_admin ideas_gen_prod > backup.sql
```

### Updates

```bash
# Update to latest version
./scripts/deploy.sh update

# Manual update
git pull
docker-compose up -d --build
```

## 🔧 Advanced Configuration

### Custom SSL Certificates

1. Place your certificates in the SSL directory:
```bash
mkdir -p /etc/ssl/certs/ideas-gen
cp your-cert.crt /etc/ssl/certs/ideas-gen/
cp your-key.key /etc/ssl/certs/ideas-gen/
```

2. Update SSL_CERT_PATH in .env:
```env
SSL_CERT_PATH=/etc/ssl/certs/ideas-gen
```

### Custom Domain Setup

1. Configure DNS to point to your server
2. Update DOMAIN_NAME in .env
3. Restart services:
```bash
docker-compose up -d
```

### Production Tuning

For high-traffic deployments, consider:

1. **Resource Limits**: Add memory/CPU limits to docker-compose.yml
2. **Load Balancing**: Use multiple backend replicas
3. **Database Tuning**: Optimize PostgreSQL settings
4. **Monitoring**: Add Prometheus/Grafana monitoring

## 🐛 Troubleshooting

### Common Issues

#### Services Won't Start
```bash
# Check logs for errors
docker-compose logs

# Check Docker daemon
docker info

# Verify disk space
df -h
```

#### Database Connection Issues
```bash
# Check database health
docker-compose exec database pg_isready -U ideas_admin

# Reset database
docker-compose down -v
docker-compose up database -d
```

#### Frontend Build Issues
```bash
# Rebuild frontend only
docker-compose build frontend
docker-compose up -d frontend
```

#### Permission Issues
```bash
# Fix Docker permissions (Linux)
sudo chown -R $USER:docker /var/run/docker.sock
```

### Performance Issues

#### Slow Response Times
1. Check system resources: `docker stats`
2. Review nginx logs: `docker-compose logs frontend`
3. Monitor database queries: `docker-compose logs database`

#### High Memory Usage
1. Optimize Node.js memory: Add `NODE_OPTIONS=--max-old-space-size=512` to backend environment
2. Tune PostgreSQL: Adjust `shared_buffers` and `work_mem`

## 🔄 Development vs Production

### Development Mode (Localhost)
- Uses HTTP only
- Relaxed CORS settings
- Debug logging enabled
- Hot reload for frontend development

### Production Mode
- HTTPS enforcement
- Strict security headers
- Compressed assets
- Rate limiting enabled
- Health monitoring

## 📚 Additional Resources

- [Docker Documentation](https://docs.docker.com/)
- [Docker Compose Reference](https://docs.docker.com/compose/)
- [Azure AD Integration Guide](../AUTHENTICATION_GUIDE.md)
- [OpenAI API Documentation](https://platform.openai.com/docs)

## 🆘 Support

For deployment issues:

1. Check the troubleshooting section above
2. Review service logs: `docker-compose logs`
3. Verify configuration: `docker-compose config`
4. Check system resources: `docker stats`

## 🏷️ Version Information

- **Docker Compose Version**: 3.8
- **Node.js Version**: 18 (Alpine)
- **PostgreSQL Version**: 15 (Alpine)
- **Nginx Version**: Latest (Alpine)

---

**Generated with [Claude Code](https://claude.ai/code)**

*This deployment setup provides enterprise-grade security, scalability, and maintainability for the Ideas Generator 2025 application.*