Files

Michael DiLeo 74324d5a1b add source code and readme

2025-12-24 14:35:17 +01:00

6.8 KiB

Raw Blame History

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

# Build latest version
./build.sh

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

Build Process

Base Image: Downloads BookWyrm production branch, installs Python dependencies
Web Container: Adds Nginx + Gunicorn configuration, optimized for HTTP serving
Worker Container: Adds Celery configuration for background task processing
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

# 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

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

# 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

6.8 KiB Raw Blame History