# Pixelfed Kubernetes-Optimized Containers This directory contains **separate, optimized Docker containers** for Pixelfed v0.12.6 designed specifically for Kubernetes deployment with your infrastructure. ## 🏗️ **Architecture Overview** ### **Three-Container Design** 1. **`pixelfed-base`** - Shared foundation image with all Pixelfed dependencies 2. **`pixelfed-web`** - Web server handling HTTP requests (Nginx + PHP-FPM) 3. **`pixelfed-worker`** - Background job processing (Laravel Horizon + Scheduler) ### **Why Separate Containers?** ✅ **Independent Scaling**: Scale web and workers separately based on load ✅ **Better Resource Management**: Optimize CPU/memory for each workload type ✅ **Enhanced Monitoring**: Separate metrics for web performance vs queue processing ✅ **Fault Isolation**: Web issues don't affect background processing and vice versa ✅ **Rolling Updates**: Update web and workers independently ✅ **Kubernetes Native**: Works perfectly with HPA, resource limits, and service mesh ## 🚀 **Quick Start** ### **Build All Containers** ```bash # From the build/ directory ./build-all.sh ``` This will: 1. Build the base image with all Pixelfed dependencies 2. Build the web container with Nginx + PHP-FPM 3. Build the worker container with Horizon + Scheduler 4. Push to your Harbor registry: `` ### **Individual Container Builds** ```bash # Build just web container cd pixelfed-web && docker build --platform linux/arm64 \ -t /pixelfed/web:v6 . # Build just worker container cd pixelfed-worker && docker build --platform linux/arm64 \ -t /pixelfed/worker:v0.12.6 . ``` ## 📦 **Container Details** ### **pixelfed-web** - Web Server Container **Purpose**: Handle HTTP requests, API calls, file uploads **Components**: - Nginx (optimized with rate limiting, gzip, security headers) - PHP-FPM (tuned for web workload with connection pooling) - Static asset serving with CDN fallback **Resources**: Optimized for HTTP response times **Health Check**: `curl -f http://localhost:80/api/v1/instance` **Scaling**: Based on HTTP traffic, CPU usage ### **pixelfed-worker** - Background Job Container **Purpose**: Process federation, image optimization, emails, scheduled tasks **Components**: - Laravel Horizon (queue management with Redis) - Laravel Scheduler (cron-like task scheduling) - Optional high-priority worker for urgent tasks **Resources**: Optimized for background processing throughput **Health Check**: `php artisan horizon:status` **Scaling**: Based on queue depth, memory usage ## ⚙️ **Configuration** ### **Environment Variables** Both containers share the same configuration: #### **Required** ```bash APP_DOMAIN=pixelfed.keyboardvagabond.com DB_HOST=postgresql-shared-rw.postgresql-system.svc.cluster.local DB_DATABASE=pixelfed DB_USERNAME=pixelfed DB_PASSWORD= ``` #### **Redis Configuration** ```bash REDIS_HOST=redis-ha-haproxy.redis-system.svc.cluster.local REDIS_PORT=6379 REDIS_PASSWORD= ``` #### **S3 Media Storage (Backblaze B2)** ```bash # Enable cloud storage with dedicated bucket approach PF_ENABLE_CLOUD=true DANGEROUSLY_SET_FILESYSTEM_DRIVER=s3 FILESYSTEM_DRIVER=s3 FILESYSTEM_CLOUD=s3 FILESYSTEM_DISK=s3 # Backblaze B2 S3-compatible configuration AWS_ACCESS_KEY_ID= AWS_SECRET_ACCESS_KEY= AWS_DEFAULT_REGION=eu-central-003 AWS_BUCKET=pixelfed-bucket AWS_URL=https://pm.keyboardvagabond.com/ AWS_ENDPOINT= AWS_USE_PATH_STYLE_ENDPOINT=false AWS_ROOT= AWS_VISIBILITY=public # CDN Configuration for media delivery CDN_DOMAIN=pm.keyboardvagabond.com ``` #### **Email (SMTP)** ```bash MAIL_MAILER=smtp MAIL_HOST= MAIL_PORT=587 MAIL_USERNAME=pixelfed@mail.keyboardvagabond.com MAIL_PASSWORD= MAIL_ENCRYPTION=tls MAIL_FROM_ADDRESS=pixelfed@mail.keyboardvagabond.com MAIL_FROM_NAME="Pixelfed at Keyboard Vagabond" ``` ### **Container-Specific Configuration** #### **Web Container Only** ```bash PIXELFED_INIT_CONTAINER=true # Only set on ONE web pod ``` #### **Worker Container Only** ```bash PIXELFED_INIT_CONTAINER=false # Never set on worker pods ``` ## 🎯 **Deployment Strategy** ### **Initialization Pattern** 1. **First Web Pod**: Set `PIXELFED_INIT_CONTAINER=true` - Runs database migrations - Generates application key - Imports initial data 2. **Additional Web Pods**: Set `PIXELFED_INIT_CONTAINER=false` - Skip initialization tasks - Start faster 3. **All Worker Pods**: Set `PIXELFED_INIT_CONTAINER=false` - Never run database migrations - Focus on background processing ### **Scaling Recommendations** #### **Web Containers** - **Start**: 2 replicas for high availability - **Scale Up**: When CPU > 70% or response time > 200ms - **Resources**: 4 CPU, 4GB RAM (medium+ tier) #### **Worker Containers** - **Start**: 1 replica for basic workload - **Scale Up**: When queue depth > 100 or processing lag > 5 minutes - **Resources**: 2 CPU, 4GB RAM initially, scale to 4 CPU, 8GB for heavy federation ## 📊 **Monitoring Integration** ### **OpenObserve Dashboards** #### **Web Container Metrics** - HTTP response times - Request rates by endpoint - PHP-FPM pool status - Nginx connection metrics - Rate limiting effectiveness #### **Worker Container Metrics** - Queue processing rates - Job failure rates - Horizon supervisor status - Memory usage for image processing - Federation activity ### **Health Checks** #### **Web**: HTTP-based health check ```bash curl -f http://localhost:80/api/v1/instance ``` #### **Worker**: Horizon status check ```bash php artisan horizon:status ``` ## 🔄 **Updates & Maintenance** ### **Updating Pixelfed Version** 1. Update `PIXELFED_VERSION` in `pixelfed-base/Dockerfile` 2. Update `VERSION` in `build-all.sh` 3. Run `./build-all.sh` 4. Deploy web containers first, then workers ### **Rolling Updates** ```bash # Update web containers first kubectl rollout restart deployment pixelfed-web # Wait for web to be healthy kubectl rollout status deployment pixelfed-web # Then update workers kubectl rollout restart deployment pixelfed-worker ``` ## 🛠️ **Troubleshooting** ### **Common Issues** #### **Database Connection** ```bash # Check from web container kubectl exec -it pixelfed-web-xxx -- php artisan migrate:status # Check from worker container kubectl exec -it pixelfed-worker-xxx -- php artisan queue:work --once ``` #### **Queue Processing** ```bash # Check Horizon status kubectl exec -it pixelfed-worker-xxx -- php artisan horizon:status # View queue stats kubectl exec -it pixelfed-worker-xxx -- php artisan queue:work --once --verbose ``` #### **Storage Issues** ```bash # Test S3 connection kubectl exec -it pixelfed-web-xxx -- php artisan storage:link # Check media upload curl -v https://pixelfed.keyboardvagabond.com/api/v1/media ``` ### **Performance Optimization** #### **Web Container Tuning** - Adjust PHP-FPM pool size in Dockerfile - Tune Nginx worker connections - Enable OPcache optimizations #### **Worker Container Tuning** - Increase Horizon worker processes - Adjust queue processing timeouts - Scale based on queue metrics ## 🔗 **Integration with Your Infrastructure** ### **Perfect Fit For Your Setup** - ✅ **PostgreSQL**: Uses your CloudNativePG cluster with read replicas - ✅ **Redis**: Integrates with your Redis cluster - ✅ **S3 Storage**: Leverages Backblaze B2 + Cloudflare CDN - ✅ **Monitoring**: Ready for OpenObserve metrics collection - ✅ **SSL**: Works with your cert-manager + Let's Encrypt setup - ✅ **DNS**: Compatible with external-dns + Cloudflare - ✅ **Auth**: Ready for Authentik SSO integration ### **Next Steps** 1. ✅ Build containers with `./build-all.sh` 2. ✅ Create Kubernetes manifests for both deployments 3. ✅ Set up PostgreSQL database and user 4. ✅ Configure ingress for `pixelfed.keyboardvagabond.com` 5. ❌ Integrate with Authentik for SSO 6. ❌ Configure Cloudflare Turnstile for spam protection 7. ✅ Use enhanced spam filter instead of recaptcha --- **Built with ❤️ for your sophisticated Kubernetes infrastructure**