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

# 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

# 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:

# 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

# 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

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

# 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

# Check resource usage
docker stats littleshop_prod

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

Database Issues

# 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

# 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

# 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.