# SolarBank IoT Dashboard - Production Deployment Guide

This guide will walk you through deploying the SolarBank IoT Dashboard to a production server with SSL certificates, security hardening, and monitoring.

## Prerequisites

Before starting the deployment, ensure your server meets these requirements:

### System Requirements
- **OS**: Ubuntu 20.04+ / CentOS 8+ / Debian 11+
- **RAM**: Minimum 4GB, Recommended 8GB+
- **CPU**: Minimum 2 cores, Recommended 4+ cores
- **Storage**: Minimum 20GB free space
- **Network**: Public IP address with ports 80 and 443 accessible

### Software Requirements
- Docker 20.10+
- Docker Compose 2.0+
- Git
- Curl
- A registered domain name pointing to your server

### Domain and DNS Setup
1. Register a domain name (e.g., `yourdomain.com`)
2. Create an A record pointing to your server's public IP address
3. Wait for DNS propagation (can take up to 24 hours)

## Quick Start

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

### 2. Configure Environment Variables
```bash
# Copy the production environment template
cp environment.prod.example .env.prod

# Edit the configuration with your values
nano .env.prod
```

**Critical values to change in `.env.prod`:**
- `DOMAIN_NAME`: Your actual domain (e.g., `example.com`)
- `EMAIL`: Your email for Let's Encrypt notifications
- `SECRET_KEY`: Generate with `python -c "import secrets; print(secrets.token_urlsafe(32))"`
- `JWT_SECRET_KEY`: Generate with `python -c "import secrets; print(secrets.token_urlsafe(32))"`
- `POSTGRES_PASSWORD`: Strong database password
- `POSTGRES_INITDB_ROOT_PASSWORD`: Strong root password
- `BACKEND_CORS_ORIGINS`: Your domain URLs in JSON format

### 3. Run the Deployment Script
```bash
# Make scripts executable
chmod +x scripts/*.sh

# Run the deployment
./scripts/deploy.sh
```

The deployment script will:
- Check system requirements
- Validate environment configuration
- Set up SSL certificates with Let's Encrypt
- Build and deploy all services
- Run database migrations
- Set up automated backups
- Perform health checks

### 4. Verify Deployment
After deployment, your application should be accessible at:
- **Frontend**: `https://yourdomain.com`
- **API**: `https://yourdomain.com/api`
- **API Documentation**: `https://yourdomain.com/api/docs`

## Detailed Configuration

### Environment Variables Reference

#### Project Configuration
```bash
PROJECT_NAME=SolarBank IoT Dashboard
API_PREFIX=/api
DEBUG=false
ENV=production
```

#### Security Configuration
```bash
SECRET_KEY=your-secret-key-here              # Generate random 32+ chars
JWT_SECRET_KEY=your-jwt-secret-key-here      # Generate random 32+ chars
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=11520            # 8 days
```

#### CORS Configuration
```bash
# JSON array of allowed origins
BACKEND_CORS_ORIGINS=["https://yourdomain.com", "https://www.yourdomain.com"]
```

#### Database Configuration
```bash
POSTGRES_SERVER=db
POSTGRES_USER=solarbank
POSTGRES_PASSWORD=secure-password-here       # Change this!
POSTGRES_DB=solarbank_iot
POSTGRES_INITDB_ROOT_PASSWORD=root-password  # Change this!
```

#### Frontend Configuration
```bash
REACT_APP_API_URL=https://yourdomain.com/api
REACT_APP_MAPBOX_TOKEN=optional-mapbox-token
```

#### SSL/Domain Configuration
```bash
DOMAIN_NAME=yourdomain.com                   # Your actual domain
EMAIL=your-email@domain.com                 # For Let's Encrypt
```

## Advanced Configuration

### Custom SSL Certificates
If you have your own SSL certificates instead of using Let's Encrypt:

1. Place your certificates in `nginx/certbot/conf/live/yourdomain.com/`:
   - `fullchain.pem`: Full certificate chain
   - `privkey.pem`: Private key

2. Skip SSL setup during deployment:
   ```bash
   ./scripts/deploy.sh --no-ssl
   ```

### Database Backups
Automated backups are configured to run daily at 2 AM. Manual backup:
```bash
./scripts/backup-database.sh
```

Restore from backup:
```bash
# Stop the application
docker-compose -f docker-compose.prod.yml down

# Restore database
gunzip -c backups/solarbank_backup_YYYYMMDD_HHMMSS.sql.gz | \
docker-compose -f docker-compose.prod.yml exec -T db \
psql -U solarbank -d solarbank_iot

# Restart application
docker-compose -f docker-compose.prod.yml up -d
```

### Monitoring and Logs
View service logs:
```bash
# All services
docker-compose -f docker-compose.prod.yml logs -f

# Specific service
docker-compose -f docker-compose.prod.yml logs -f backend
docker-compose -f docker-compose.prod.yml logs -f frontend
docker-compose -f docker-compose.prod.yml logs -f nginx
```

Check service status:
```bash
docker-compose -f docker-compose.prod.yml ps
```

Health check endpoints:
- Backend: `https://yourdomain.com/api/health`
- Frontend: `https://yourdomain.com/health`

## Maintenance

### Updating the Application
```bash
# Update deployment with latest changes
./scripts/deploy.sh --update
```

### Renewing SSL Certificates
SSL certificates auto-renew via the certbot container. Manual renewal:
```bash
docker-compose -f docker-compose.prod.yml exec certbot certbot renew
docker-compose -f docker-compose.prod.yml exec nginx nginx -s reload
```

### Scaling Services
To handle more traffic, scale backend instances:
```bash
docker-compose -f docker-compose.prod.yml up -d --scale backend=3
```

## Security Considerations

### Server Security
1. **Firewall Configuration**:
   ```bash
   # Ubuntu/Debian
   ufw allow ssh
   ufw allow 80/tcp
   ufw allow 443/tcp
   ufw enable
   
   # CentOS/RHEL
   firewall-cmd --permanent --add-service=ssh
   firewall-cmd --permanent --add-service=http
   firewall-cmd --permanent --add-service=https
   firewall-cmd --reload
   ```

2. **SSH Hardening**:
   - Disable root login
   - Use SSH keys instead of passwords
   - Change default SSH port

3. **System Updates**:
   ```bash
   # Ubuntu/Debian
   apt update && apt upgrade -y
   
   # CentOS/RHEL
   yum update -y
   ```

### Application Security
- All passwords are hashed using bcrypt
- JWT tokens have configurable expiration
- CORS is properly configured
- Security headers are set via nginx
- Rate limiting is enabled for API endpoints

### Database Security
- Database is not exposed to the internet
- Strong passwords are required
- Regular backups are maintained
- Database runs as non-root user

## Troubleshooting

### Common Issues

#### SSL Certificate Issues
```bash
# Check certificate status
docker-compose -f docker-compose.prod.yml logs certbot

# Test certificate renewal
docker-compose -f docker-compose.prod.yml exec certbot certbot renew --dry-run

# Regenerate certificates
./scripts/deploy.sh --ssl-only
```

#### Database Connection Issues
```bash
# Check database logs
docker-compose -f docker-compose.prod.yml logs db

# Test database connection
docker-compose -f docker-compose.prod.yml exec db psql -U solarbank -d solarbank_iot
```

#### Service Not Starting
```bash
# Check service status
docker-compose -f docker-compose.prod.yml ps

# Check specific service logs
docker-compose -f docker-compose.prod.yml logs backend
```

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

# Monitor system resources
htop
df -h
free -h
```

### Getting Help
If you encounter issues:
1. Check the logs first
2. Verify your environment configuration
3. Ensure your domain DNS is properly configured
4. Check that required ports are open
5. Verify SSL certificates are valid

## Production Checklist

Before going live, ensure:

- [ ] Domain DNS is properly configured
- [ ] Environment variables are set correctly
- [ ] SSL certificates are installed and valid
- [ ] All services are running and healthy
- [ ] Database backups are working
- [ ] Monitoring is configured
- [ ] Firewall is properly configured
- [ ] Application is thoroughly tested
- [ ] Login credentials are secure
- [ ] Rate limiting is working
- [ ] Security headers are present

## Performance Optimization

### Database Optimization
```sql
-- Connect to database
docker-compose -f docker-compose.prod.yml exec db psql -U solarbank -d solarbank_iot

-- Create indexes for better performance
CREATE INDEX IF NOT EXISTS idx_telemetry_device_id ON telemetry(device_id);
CREATE INDEX IF NOT EXISTS idx_telemetry_timestamp ON telemetry(timestamp);
CREATE INDEX IF NOT EXISTS idx_logs_device_id ON logs(device_id);
CREATE INDEX IF NOT EXISTS idx_logs_timestamp ON logs(timestamp);
```

### Nginx Optimization
The production nginx configuration includes:
- Gzip compression
- Static file caching
- Rate limiting
- Security headers

### Application Monitoring
Consider integrating external monitoring services:
- **Uptime Monitoring**: Pingdom, UptimeRobot
- **Error Tracking**: Sentry (configure SENTRY_DSN in .env.prod)
- **Performance Monitoring**: New Relic, DataDog
- **Log Management**: ELK Stack, Splunk

## Support

For additional support or questions about deployment:
1. Check the application logs
2. Review this documentation
3. Check the GitHub issues
4. Contact the development team

---

**Remember**: Always test deployments in a staging environment before deploying to production!