Keybard-Vagabond-Demo/build/bookwyrm/README.md

# BookWyrm Container Build

Multi-stage Docker container build for BookWyrm social reading platform, optimized for the Keyboard Vagabond infrastructure.

## 🏗️ **Architecture**

### **Multi-Stage Build Pattern**
Following the established Keyboard Vagabond pattern with optimized, production-ready containers:

- **`bookwyrm-base`** - Shared foundation image with BookWyrm source code and dependencies
- **`bookwyrm-web`** - Web server container (Nginx + Django/Gunicorn)
- **`bookwyrm-worker`** - Background worker container (Celery + Beat)

### **Container Features**
- **Base Image**: Python 3.11 slim with multi-stage optimization (~60% size reduction from 1GB+ to ~400MB)
- **Security**: Non-root execution with dedicated `bookwyrm` user (UID 1000)
- **Process Management**: Supervisor for multi-process orchestration
- **Health Checks**: Built-in health monitoring for both web and worker containers
- **Logging**: All logs directed to stdout/stderr for Kubernetes log collection
- **ARM64 Optimized**: Built specifically for ARM64 architecture

## 📁 **Directory Structure**

```
build/bookwyrm/
├── build.sh                    # Main build script
├── README.md                   # This documentation
├── bookwyrm-base/              # Base image with shared components
│   ├── Dockerfile              # Multi-stage base build
│   └── entrypoint-common.sh    # Shared initialization utilities
├── bookwyrm-web/               # Web server container
│   ├── Dockerfile              # Web-specific build
│   ├── nginx.conf              # Optimized Nginx configuration
│   ├── supervisord-web.conf    # Process management for web services
│   └── entrypoint-web.sh       # Web container initialization
└── bookwyrm-worker/            # Background worker container
    ├── Dockerfile              # Worker-specific build
    ├── supervisord-worker.conf # Process management for worker services
    └── entrypoint-worker.sh    # Worker container initialization
```

## 🔨 **Building Containers**

### **Prerequisites**
- Docker with ARM64 support
- Access to Harbor registry (`<YOUR_REGISTRY_URL>`)
- Active Harbor login session

### **Build All Containers**
```bash
# Build latest version
./build.sh

# Build specific version
./build.sh v1.0.0
```

### **Build Process**
1. **Base Image**: Downloads BookWyrm production branch, installs Python dependencies
2. **Web Container**: Adds Nginx + Gunicorn configuration, optimized for HTTP serving
3. **Worker Container**: Adds Celery configuration for background task processing
4. **Registry Push**: Interactive push to Harbor registry with confirmation

**Build Optimizations**:
- **`.dockerignore`**: Automatically excludes Python bytecode, cache files, and development artifacts
- **Multi-stage build**: Separates build dependencies from runtime, reducing final image size
- **Manual cleanup**: Removes documentation, tests, and unnecessary files
- **Runtime compilation**: Static assets and theme compilation moved to runtime to avoid requiring environment variables during build

### **Manual Build Steps**
```bash
# Build base image first
cd bookwyrm-base
docker build --platform linux/arm64 -t bookwyrm-base:latest .
cd ..

# Build web container
cd bookwyrm-web  
docker build --platform linux/arm64 -t <YOUR_REGISTRY_URL>/library/bookwyrm-web:latest .
cd ..

# Build worker container
cd bookwyrm-worker
docker build --platform linux/arm64 -t <YOUR_REGISTRY_URL>/library/bookwyrm-worker:latest .
```

## 🎯 **Container Specifications**

### **Web Container (`bookwyrm-web`)**
- **Services**: Nginx (port 80) + Gunicorn (port 8000)
- **Purpose**: HTTP requests, API endpoints, static file serving
- **Health Check**: HTTP health endpoint monitoring
- **Features**:
  - Rate limiting (login: 5/min, API: 30/min)
  - Static file caching (1 year expiry)
  - Security headers
  - WebSocket support for real-time features

### **Worker Container (`bookwyrm-worker`)**
- **Services**: Celery Worker + Celery Beat + Celery Flower (optional)
- **Purpose**: Background tasks, scheduled jobs, ActivityPub federation
- **Health Check**: Redis broker connectivity monitoring
- **Features**:
  - Multi-queue processing (default, high_priority, low_priority)
  - Scheduled task execution
  - Task monitoring via Flower

## 📊 **Resource Requirements**

### **Production Recommendations**
```yaml
# Web Container
resources:
  requests:
    cpu: 1000m      # 1 CPU core
    memory: 2Gi     # 2GB RAM
  limits:
    cpu: 2000m      # 2 CPU cores
    memory: 4Gi     # 4GB RAM

# Worker Container  
resources:
  requests:
    cpu: 500m       # 0.5 CPU core
    memory: 1Gi     # 1GB RAM
  limits:
    cpu: 1000m      # 1 CPU core
    memory: 2Gi     # 2GB RAM
```

## 🔧 **Configuration**

### **Required Environment Variables**
Both containers require these environment variables for proper operation:

```bash
# Database Configuration
DB_HOST=postgresql-shared-rw.postgresql-system.svc.cluster.local
DB_PORT=5432
DB_NAME=bookwyrm
DB_USER=bookwyrm_user
DB_PASSWORD=<REPLACE_WITH_ACTUAL_PASSWORD>

# Redis Configuration  
REDIS_BROKER_URL=redis://:<REPLACE_WITH_REDIS_PASSWORD>@redis-ha-haproxy.redis-system.svc.cluster.local:6379/3
REDIS_ACTIVITY_URL=redis://:<REPLACE_WITH_REDIS_PASSWORD>@redis-ha-haproxy.redis-system.svc.cluster.local:6379/4

# Application Settings
SECRET_KEY=<REPLACE_WITH_DJANGO_SECRET_KEY>
DEBUG=false
USE_HTTPS=true
DOMAIN=bookwyrm.keyboardvagabond.com

# S3 Storage
USE_S3=true
AWS_ACCESS_KEY_ID=<REPLACE_WITH_S3_ACCESS_KEY>
AWS_SECRET_ACCESS_KEY=<REPLACE_WITH_S3_SECRET_KEY>
AWS_STORAGE_BUCKET_NAME=bookwyrm-bucket
AWS_S3_REGION_NAME=eu-central-003
AWS_S3_ENDPOINT_URL=<REPLACE_WITH_S3_ENDPOINT>
AWS_S3_CUSTOM_DOMAIN=https://bm.keyboardvagabond.com

# Email Configuration
EMAIL_HOST=<YOUR_SMTP_SERVER>
EMAIL_PORT=587
EMAIL_HOST_USER=bookwyrm@mail.keyboardvagabond.com
EMAIL_HOST_PASSWORD=<REPLACE_WITH_EMAIL_PASSWORD>
EMAIL_USE_TLS=true
```

## 🚀 **Deployment**

These containers are designed for Kubernetes deployment with:
- **Zero Trust**: Cloudflare tunnel integration (no external ports)
- **Storage**: Longhorn persistent volumes + S3 media storage
- **Monitoring**: OpenObserve ServiceMonitor integration
- **Scaling**: Horizontal Pod Autoscaler ready

## 📝 **Notes**

- **ARM64 Optimized**: Built specifically for ARM64 nodes
- **Size Optimized**: Multi-stage builds reduce final image size by ~75%
- **Security Hardened**: Non-root execution, minimal dependencies
- **Production Ready**: Comprehensive health checks, logging, and error handling
- **GitOps Ready**: Compatible with Flux CD deployment patterns

## 🔗 **Related Documentation**

- [BookWyrm Official Documentation](https://docs.joinbookwyrm.com/)
- [Kubernetes Manifests](../../manifests/applications/bookwyrm/)
- [Infrastructure Setup](../../manifests/infrastructure/)