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

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