ukaiautomation/DOCKER-DEPLOYMENT-GUIDE.md

# UK Data Services - Docker Deployment Guide

## Overview
This guide covers deploying the UK Data Services website using Docker containers for development, staging, and production environments.

## Prerequisites
- Docker Engine 20.10+
- Docker Compose 2.0+
- 2GB+ RAM available
- 10GB+ disk space

## Quick Start (Development)

### 1. Clone Repository
```bash
git clone <your-repo-url>
cd ukdataservices
```

### 2. Start Development Environment
```bash
# Start all services
docker-compose -f docker-compose-dev.yml up -d

# View logs
docker-compose -f docker-compose-dev.yml logs -f web

# Stop services
docker-compose -f docker-compose-dev.yml down
```

### 3. Access Services
- **Website**: http://localhost:8080
- **phpMyAdmin**: http://localhost:8081
- **Mailhog**: http://localhost:8025

## Production Deployment

### 1. Environment Setup
```bash
# Create production directories
mkdir -p {logs,uploads,cache,backups,ssl}

# Set permissions
chmod 755 logs uploads cache backups
chmod 700 ssl
```

### 2. Configure Environment Variables
Create `.env` file:
```env
# Database
DB_ROOT_PASSWORD=your_secure_root_password
DB_PASSWORD=your_secure_web_password

# Security
SECURITY_SALT=your_unique_salt_here
API_SECRET_KEY=your_api_secret_here

# Application
SITE_URL=https://ukdataservices.co.uk
CONTACT_EMAIL=info@ukdataservices.co.uk
ANALYTICS_ID=your_ga_id
```

### 3. SSL Certificates
```bash
# Place SSL certificates in ssl/ directory
ssl/
├── cert.pem
├── privkey.pem
└── chain.pem
```

### 4. Deploy Production
```bash
# Build and start services
docker-compose -f docker-compose-production.yml up -d

# Check status
docker-compose -f docker-compose-production.yml ps

# View logs
docker-compose -f docker-compose-production.yml logs -f
```

## Container Management

### Building Images
```bash
# Build optimized production image
docker build -f Dockerfile-optimized -t ukds-web:latest .

# Build development image
docker build -t ukds-web:dev .
```

### Container Operations
```bash
# Execute commands in containers
docker exec -it ukds-web bash
docker exec -it ukds-database mysql -u root -p

# View container logs
docker logs ukds-web -f
docker logs ukds-database -f

# Monitor resource usage
docker stats
```

### Database Management
```bash
# Create database backup
docker exec ukds-database mysqldump -u root -p ukdataservices > backup.sql

# Restore database
docker exec -i ukds-database mysql -u root -p ukdataservices < backup.sql

# Access MySQL shell
docker exec -it ukds-database mysql -u root -p
```

## Scaling and Load Balancing

### Horizontal Scaling
```bash
# Scale web containers
docker-compose -f docker-compose-production.yml up -d --scale web=3

# Use with load balancer (nginx, traefik)
```

### Load Balancer Configuration (nginx)
```nginx
upstream ukds_backend {
    server 127.0.0.1:8080;
    server 127.0.0.1:8081;
    server 127.0.0.1:8082;
}

server {
    listen 80;
    server_name ukdataservices.co.uk;
    
    location / {
        proxy_pass http://ukds_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

## Monitoring and Maintenance

### Health Checks
```bash
# Check container health
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# Application health check
curl -f http://localhost/health-check.php || echo "Health check failed"
```

### Log Management
```bash
# View application logs
tail -f logs/apache_access.log
tail -f logs/apache_error.log
tail -f logs/php_errors.log

# Rotate logs
docker exec ukds-web logrotate /etc/logrotate.conf
```

### Performance Monitoring
```bash
# Monitor container resources
docker stats ukds-web ukds-database ukds-redis

# Database performance
docker exec ukds-database mysqladmin -u root -p status
docker exec ukds-database mysqladmin -u root -p processlist
```

## Backup and Recovery

### Automated Backups
The production setup includes automated daily backups:
- Database backups: `backups/ukds_YYYYMMDD_HHMMSS.sql`
- Log archives: `backups/logs_YYYYMMDD_HHMMSS.tar.gz`
- Retention: 7 days

### Manual Backup
```bash
# Full site backup
tar -czf ukds_backup_$(date +%Y%m%d).tar.gz \
  --exclude='node_modules' \
  --exclude='.git' \
  --exclude='cache/*' \
  .

# Database only
docker exec ukds-database mysqldump -u root -p --all-databases > full_backup.sql
```

### Recovery Procedures
```bash
# Restore from backup
docker-compose -f docker-compose-production.yml down
docker volume rm ukdataservices_mysql_data
docker-compose -f docker-compose-production.yml up -d database
docker exec -i ukds-database mysql -u root -p < backup.sql
docker-compose -f docker-compose-production.yml up -d
```

## Security Best Practices

### Container Security
- Non-root user execution
- Read-only file systems where possible
- Minimal base images
- Regular security updates

### Network Security
```bash
# Isolate networks
docker network create --driver bridge ukds-isolated

# Firewall rules
ufw allow 80/tcp
ufw allow 443/tcp
ufw deny 3306/tcp
```

### SSL/TLS Configuration
- Use Let's Encrypt for certificates
- Enable HSTS headers
- Strong cipher suites
- Regular certificate renewal

## Troubleshooting

### Common Issues

#### Container Won't Start
```bash
# Check logs
docker logs ukds-web

# Check disk space
df -h

# Check memory
free -m
```

#### Database Connection Failed
```bash
# Verify database container
docker exec ukds-database mysqladmin -u root -p ping

# Check network connectivity
docker exec ukds-web ping database

# Verify credentials
docker exec ukds-web env | grep DB_
```

#### Performance Issues
```bash
# Monitor resource usage
docker stats

# Check PHP errors
tail -f logs/php_errors.log

# Database slow queries
docker exec ukds-database tail -f /var/log/mysql/slow.log
```

### Performance Optimization

#### PHP-FPM Configuration
```ini
# In docker/php.ini
pm.max_children = 50
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 35
```

#### MySQL Tuning
```sql
-- Check MySQL status
SHOW STATUS LIKE 'Threads_connected';
SHOW STATUS LIKE 'Questions';
SHOW STATUS LIKE 'Uptime';

-- Optimize tables
OPTIMIZE TABLE contact_submissions;
OPTIMIZE TABLE quote_requests;
```

#### Redis Cache
```bash
# Monitor Redis
docker exec ukds-redis redis-cli info memory
docker exec ukds-redis redis-cli info stats
```

## Development Workflow

### Local Development
1. Use `docker-compose-dev.yml` for development
2. Code changes are reflected immediately (volume mounting)
3. Debug with xdebug enabled
4. Use Mailhog for email testing

### Testing
```bash
# Run tests in container
docker exec ukds-web ./vendor/bin/phpunit

# PHP syntax check
find . -name "*.php" -exec docker exec ukds-web php -l {} \;
```

### Deployment Pipeline
1. **Development**: Local Docker environment
2. **Staging**: Production-like Docker setup
3. **Production**: Optimized Docker with monitoring

## Configuration Files Reference

### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `DB_HOST` | Database hostname | `database` |
| `DB_NAME` | Database name | `ukdataservices` |
| `DB_USER` | Database username | `webuser` |
| `DB_PASSWORD` | Database password | Required |
| `SITE_URL` | Site URL | `http://localhost` |
| `DEBUG_MODE` | Debug mode | `0` |

### Volume Mounts
| Host Path | Container Path | Purpose |
|-----------|----------------|---------|
| `./logs` | `/var/www/html/logs` | Application logs |
| `./uploads` | `/var/www/html/uploads` | File uploads |
| `./cache` | `/var/www/html/cache` | Application cache |
| `./ssl` | `/etc/ssl/certs/ukds` | SSL certificates |

## Support

For deployment issues:
1. Check container logs: `docker logs <container_name>`
2. Verify configuration files
3. Review resource usage: `docker stats`
4. Contact: dev@ukdataservices.co.uk

## Updates and Maintenance

### Regular Tasks
- Weekly: Review logs and performance
- Monthly: Update container images
- Quarterly: Security audit and updates

### Update Procedure
```bash
# Pull latest images
docker-compose -f docker-compose-production.yml pull

# Rebuild and restart
docker-compose -f docker-compose-production.yml up -d --build

# Verify deployment
curl -f https://ukdataservices.co.uk/health-check.php
```