littleshop/PRODUCTION.md

# LittleShop Production Deployment Guide

## Overview

This guide covers the production deployment of LittleShop with optimized Docker configuration, monitoring, and logging.

## Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│     Traefik     │    │   LittleShop    │    │   Monitoring    │
│   (Reverse      │────│   Application   │────│     Stack       │
│    Proxy)       │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │              ┌─────────────────┐
         │                       │              │   Prometheus    │
         │                       │              │    Grafana      │
         │                       │              │  AlertManager   │
         │                       │              │    Fluentd      │
         │                       │              └─────────────────┘
         │                       │
    ┌─────────────────┐    ┌─────────────────┐
    │   Let's Encrypt │    │   Persistent    │
    │  Certificates   │    │     Storage     │
    └─────────────────┘    └─────────────────┘
```

## Quick Start

### 1. Prerequisites

- Docker Engine 20.10+
- Docker Compose 2.0+
- Linux server with at least 2GB RAM
- Domain name with DNS pointing to your server

### 2. Initial Setup

```bash
# Clone repository
git clone <repository-url>
cd LittleShop

# Copy and configure environment
cp .env.production.template .env
nano .env  # Configure your secrets

# Create required directories
sudo mkdir -p /opt/littleshop/{data,uploads,logs,backups}
sudo chown -R $USER:$USER /opt/littleshop
```

### 3. Deploy Application

```bash
# Deploy production application
./deploy-production.sh

# Deploy monitoring stack (optional)
docker-compose -f docker-compose.monitoring.yml up -d
```

## Configuration Files

### Environment Configuration

The `.env` file contains all production secrets:

```env
# Required Configuration
JWT_SECRET_KEY=your-super-secret-jwt-key-minimum-32-characters
BTCPAY_SERVER_URL=https://your-btcpay-server.com
BTCPAY_STORE_ID=your-store-id
BTCPAY_API_KEY=your-api-key
BTCPAY_WEBHOOK_SECRET=your-webhook-secret

# Optional Configuration
GRAFANA_ADMIN_PASSWORD=secure-grafana-password
```

### Docker Configurations

| File | Purpose |
|------|---------|
| `Dockerfile` | Optimized production image with security hardening |
| `docker-compose.prod.yml` | Production deployment with resource limits |
| `docker-compose.monitoring.yml` | Monitoring and observability stack |

## Security Features

### Container Security

- **Chiseled Ubuntu**: Minimal attack surface with distroless-like images
- **Non-root user**: Application runs as unprivileged user
- **Read-only filesystem**: Container filesystem is read-only except for specific volumes
- **Resource limits**: Memory and CPU limits prevent resource exhaustion
- **Security options**: `no-new-privileges` prevents privilege escalation

### Network Security

- **Internal networks**: Service-to-service communication on isolated networks
- **TLS termination**: All traffic encrypted with Let's Encrypt certificates
- **Security headers**: HSTS, XSS protection, content-type sniffing protection
- **CORS policies**: Strict cross-origin resource sharing policies

### Data Security

- **Persistent volumes**: Data persisted outside containers
- **Backup strategy**: Automated database backups before deployments
- **Log retention**: Configurable log retention policies

## Monitoring and Observability

### Health Checks

The application exposes health check endpoints:

- `/health` - Application health status
- `/health/ready` - Readiness probe for Kubernetes
- `/health/live` - Liveness probe for container orchestration

### Metrics Collection

Prometheus collects metrics from:

- **Application metrics**: Custom business metrics
- **System metrics**: CPU, memory, disk, network via Node Exporter
- **Container metrics**: Docker container statistics via cAdvisor
- **Log metrics**: Log aggregation and error rates via Fluentd

### Alerting

AlertManager handles:

- **Critical alerts**: Application down, database failures
- **Warning alerts**: High resource usage, elevated error rates
- **Notification channels**: Email, webhooks, Slack integration

### Dashboards

Grafana provides:

- **Application dashboard**: Request rates, response times, error rates
- **Infrastructure dashboard**: System resources, container health
- **Business dashboard**: Orders, payments, user activity

## Deployment Process

### Zero-Downtime Deployment

The `deploy-production.sh` script implements:

1. **Health check** of existing container
2. **Database backup** before deployment
3. **Image building** with latest code
4. **Rolling update** with health verification
5. **Cleanup** of old images and containers

### Rollback Strategy

```bash
# List available backups
ls /opt/littleshop/backups/

# Restore from backup
cp /opt/littleshop/backups/littleshop-YYYYMMDD-HHMMSS.db /opt/littleshop/data/littleshop.db

# Restart application
docker-compose -f docker-compose.prod.yml restart
```

## Performance Optimization

### Docker Optimizations

- **Multi-stage builds**: Separate build and runtime stages
- **Layer caching**: Optimized layer order for build cache efficiency
- **Image size**: Minimal base images with only required dependencies
- **Build context**: Optimized `.dockerignore` excludes unnecessary files

### Application Optimizations

- **ReadyToRun images**: Pre-compiled for faster startup
- **Garbage collection**: Optimized GC settings for container environments
- **Connection pooling**: Database connection pooling enabled
- **Compression**: Response compression enabled

### Resource Management

```yaml
deploy:
  resources:
    limits:
      memory: 1G      # Maximum memory usage
      cpus: '1.0'     # Maximum CPU cores
    reservations:
      memory: 512M    # Guaranteed memory
      cpus: '0.5'     # Guaranteed CPU cores
```

## Troubleshooting

### Common Issues

#### Container Won't Start

```bash
# Check container logs
docker-compose -f docker-compose.prod.yml logs littleshop

# Check health status
docker exec littleshop_prod curl -f http://localhost:8080/health
```

#### High Memory Usage

```bash
# Check resource usage
docker stats littleshop_prod

# Review memory configuration
docker inspect littleshop_prod | grep -i memory
```

#### Database Issues

```bash
# Check database connectivity
docker exec littleshop_prod sqlite3 /app/data/littleshop.db ".tables"

# Restore from backup
cp /opt/littleshop/backups/latest.db /opt/littleshop/data/littleshop.db
```

### Log Analysis

```bash
# Application logs
docker-compose -f docker-compose.prod.yml logs -f littleshop

# System logs
journalctl -u docker -f

# Aggregated logs (if monitoring stack deployed)
docker exec littleshop_fluentd tail -f /fluentd/log/output/littleshop.*.log
```

## Maintenance

### Regular Tasks

1. **Update base images** monthly
2. **Review security alerts** weekly
3. **Clean up old logs** based on retention policy
4. **Backup verification** monthly
5. **Performance review** quarterly

### Updates

```bash
# Update application
git pull
./deploy-production.sh

# Update monitoring stack
docker-compose -f docker-compose.monitoring.yml pull
docker-compose -f docker-compose.monitoring.yml up -d
```

## Support

For issues and questions:

1. Check logs first: `docker-compose logs`
2. Review monitoring dashboards
3. Check health endpoints
4. Review this documentation
5. Contact system administrator

---

**Production Deployment Status**: ✅ Ready for production use with enterprise-grade monitoring and security.