Keybard-Vagabond-Demo/manifests/applications/pixelfed/README.md

# Pixelfed - Photo Sharing for the Fediverse

Pixelfed is a free and open-source photo sharing platform that implements the ActivityPub protocol for federation. This deployment provides a complete Pixelfed instance optimized for the Keyboard Vagabond community.

## 🎯 **Access Information**

- **URL**: `https://pixelfed.keyboardvagabond.com`
- **Federation**: ActivityPub enabled, federated with other fediverse instances
- **Registration**: Open registration with email verification
- **User Limit**: 200 Monthly Active Users

## 🏗️ **Architecture**

### **Multi-Container Design**
- **Web Container**: Nginx + PHP-FPM for HTTP requests
- **Worker Container**: Laravel Horizon + Scheduler for background jobs
- **Database**: PostgreSQL (shared cluster with HA)
- **Cache**: Redis (shared cluster)
- **Storage**: Backblaze B2 S3 + Cloudflare CDN
- **Mail**: SMTP

### **Resource Allocation**
- **Web**: 2 CPU cores, 4GB RAM (medium+ recommendation)
- **Worker**: 1 CPU core, 2GB RAM
- **Storage**: 10GB app storage + 5GB cache

## 📁 **File Structure**

```
manifests/applications/pixelfed/
├── namespace.yaml           # pixelfed-application namespace
├── secret.yaml             # Environment variables and credentials
├── storage.yaml             # Persistent volumes for app and cache
├── deployment-web.yaml      # Web server deployment
├── deployment-worker.yaml   # Background worker deployment  
├── service.yaml             # Internal service for web pods
├── ingress.yaml             # External access with SSL
├── monitoring.yaml          # OpenObserve metrics collection
├── kustomization.yaml       # Kustomize configuration
└── README.md               # This documentation
```

## 🔧 **Configuration**

### **Database Configuration**
- **Primary**: `postgresql-shared-rw.postgresql-system.svc.cluster.local`
- **Replica**: `postgresql-shared-ro.postgresql-system.svc.cluster.local`
- **Database**: `pixelfed`
- **User**: `pixelfed`

### **Redis Configuration**
- **Primary**: `redis-ha-haproxy.redis-system.svc.cluster.local`
- **Port**: `6379`
- **Usage**: Sessions, cache, queues

### **S3 Media Storage**
- **Provider**: Backblaze B2
- **Bucket**: `media-keyboard-vagabond`
- **CDN**: `https://media.keyboardvagabond.com`
- **Region**: `us-west-004`

### **SMTP Configuration**
- **Provider**: SMTP
- **Host**: `<YOUR_SMTP_SERVER>`
- **User**: `pixelfed@mail.keyboardvagabond.com`
- **Encryption**: TLS (port 587)

## 🚀 **Deployment**

### **Prerequisites**
1. **Database Setup**: Database and user already created
2. **Secrets**: Update `secret.yaml` with:
   - Redis password
   - Backblaze B2 credentials
   - Laravel APP_KEY (generate with `php artisan key:generate`)

### **Deploy Pixelfed**
```bash
# Deploy all manifests
kubectl apply -k manifests/applications/pixelfed/

# Monitor deployment
kubectl get pods -n pixelfed-application -w

# Check ingress and certificates
kubectl get ingress,certificates -n pixelfed-application
```

### **Post-Deployment Setup**
```bash
# Generate application key (if not done in secret)
kubectl exec -it deployment/pixelfed-web -n pixelfed-application -- php artisan key:generate

# Run database migrations
kubectl exec -it deployment/pixelfed-web -n pixelfed-application -- php artisan migrate

# Import location data
kubectl exec -it deployment/pixelfed-web -n pixelfed-application -- php artisan import:cities

# Create admin user (optional)
kubectl exec -it deployment/pixelfed-web -n pixelfed-application -- php artisan user:create
```

## 🔍 **Monitoring & Troubleshooting**

### **Check Application Status**
```bash
# Pod status
kubectl get pods -n pixelfed-application
kubectl describe pods -n pixelfed-application

# Application logs
kubectl logs -f deployment/pixelfed-web -n pixelfed-application
kubectl logs -f deployment/pixelfed-worker -n pixelfed-application

# Check services and ingress
kubectl get svc,ingress -n pixelfed-application
```

### **Database Connectivity**
```bash
# Test database connection
kubectl exec -it deployment/pixelfed-web -n pixelfed-application -- php artisan tinker
# In tinker: DB::connection()->getPdo();
```

### **Queue Status**
```bash
# Check Horizon status
kubectl exec -it deployment/pixelfed-worker -n pixelfed-application -- php artisan horizon:status

# Check queue jobs
kubectl exec -it deployment/pixelfed-worker -n pixelfed-application -- php artisan queue:work --once
```

### **Storage & Media**
```bash
# Check storage link
kubectl exec -it deployment/pixelfed-web -n pixelfed-application -- ls -la /var/www/storage

# Test S3 connectivity
kubectl exec -it deployment/pixelfed-web -n pixelfed-application -- php artisan storage:link
```

## 🔐 **Security Features**

### **Application Security**
- HTTPS enforcement with Let's Encrypt certificates
- Session security with secure cookies
- CSRF protection enabled
- XSS protection headers
- Content Security Policy headers

### **Infrastructure Security**
- Non-root containers (www-data user)
- Pod Security Standards (restricted)
- Resource limits and requests
- Network policies ready (implement as needed)

### **Rate Limiting**
- Nginx ingress rate limiting (100 req/min)
- Pixelfed internal rate limiting
- API endpoint protection

## 🌐 **Federation & ActivityPub**

### **Federation Settings**
- **ActivityPub**: Enabled
- **Remote Follow**: Enabled
- **Shared Inbox**: Enabled
- **Public Timeline**: Disabled (local community focus)

### **Instance Configuration**
- **Description**: "Photo sharing for the Keyboard Vagabond community"
- **Contact**: `pixelfed@mail.keyboardvagabond.com`
- **Public Hashtags**: Enabled
- **Max Users**: 200 MAU

## 📊 **Performance & Scaling**

### **Current Capacity**
- **Users**: Up to 200 Monthly Active Users
- **Storage**: 10GB application + unlimited S3 media
- **Upload Limit**: 20MB per photo
- **Album Limit**: 8 photos per album

### **Scaling Options**
- **Horizontal**: Increase web/worker replicas
- **Vertical**: Increase CPU/memory limits
- **Storage**: Automatic S3 scaling via Backblaze B2
- **Database**: PostgreSQL HA cluster with read replicas

## 🔄 **Backup & Recovery**

### **Automated Backups**
- **Database**: PostgreSQL cluster backups via CloudNativePG
- **Application Data**: Longhorn S3 backup to Backblaze B2
- **Media**: Stored directly in S3 (Backblaze B2)

### **Recovery Procedures**
- **Database**: CloudNativePG point-in-time recovery
- **Application**: Longhorn volume restoration
- **Media**: Already in S3, no recovery needed

## 🔗 **Integration Points**

### **Existing Infrastructure**
- **PostgreSQL**: Shared HA cluster
- **Redis**: Shared cache cluster  
- **DNS**: External-DNS with Cloudflare
- **SSL**: cert-manager with Let's Encrypt
- **Monitoring**: OpenObserve metrics collection
- **Storage**: Longhorn + Backblaze B2 S3

### **Future Integrations**
- **Authentik SSO**: Invitation-based signup (planned)
- **Cloudflare Turnstile**: Anti-spam for registration (planned)
- **Matrix**: Cross-platform notifications (optional)

## 📝 **Maintenance Tasks**

### **Regular Maintenance**
```bash
# Update application cache
kubectl exec -it deployment/pixelfed-web -n pixelfed-application -- php artisan config:cache
kubectl exec -it deployment/pixelfed-web -n pixelfed-application -- php artisan route:cache

# Clear application cache
kubectl exec -it deployment/pixelfed-web -n pixelfed-application -- php artisan cache:clear

# Update Horizon assets
kubectl exec -it deployment/pixelfed-worker -n pixelfed-application -- php artisan horizon:publish
```

### **Updates & Upgrades**
1. **Update container images** in deployment manifests
2. **Run database migrations** after deployment
3. **Clear caches** after major updates
4. **Test functionality** before marking complete

## 📚 **References**

- [Pixelfed Documentation](https://docs.pixelfed.org/)
- [Pixelfed GitHub](https://github.com/pixelfed/pixelfed)
- [ActivityPub Specification](https://www.w3.org/TR/activitypub/)
- [Laravel Horizon Documentation](https://laravel.com/docs/horizon)