192 lines
6.8 KiB
Markdown
192 lines
6.8 KiB
Markdown
# 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/)
|