add source code and readme
This commit is contained in:
291
build/pixelfed/README.md
Normal file
291
build/pixelfed/README.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# 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: `<YOUR_REGISTRY_URL>`
|
||||
|
||||
### **Individual Container Builds**
|
||||
|
||||
```bash
|
||||
# Build just web container
|
||||
cd pixelfed-web && docker build --platform linux/arm64 \
|
||||
-t <YOUR_REGISTRY_URL>/pixelfed/web:v6 .
|
||||
|
||||
# Build just worker container
|
||||
cd pixelfed-worker && docker build --platform linux/arm64 \
|
||||
-t <YOUR_REGISTRY_URL>/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=<REPLACE_WITH_DATABASE_PASSWORD>
|
||||
```
|
||||
|
||||
#### **Redis Configuration**
|
||||
```bash
|
||||
REDIS_HOST=redis-ha-haproxy.redis-system.svc.cluster.local
|
||||
REDIS_PORT=6379
|
||||
REDIS_PASSWORD=<REPLACE_WITH_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=<REPLACE_WITH_S3_ACCESS_KEY>
|
||||
AWS_SECRET_ACCESS_KEY=<REPLACE_WITH_S3_SECRET_KEY>
|
||||
AWS_DEFAULT_REGION=eu-central-003
|
||||
AWS_BUCKET=pixelfed-bucket
|
||||
AWS_URL=https://pm.keyboardvagabond.com/
|
||||
AWS_ENDPOINT=<REPLACE_WITH_S3_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=<YOUR_SMTP_SERVER>
|
||||
MAIL_PORT=587
|
||||
MAIL_USERNAME=pixelfed@mail.keyboardvagabond.com
|
||||
MAIL_PASSWORD=<REPLACE_WITH_EMAIL_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**
|
||||
Reference in New Issue
Block a user