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

# 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

# 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

# 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

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

Queue Status

# 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

# 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

# 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
• Pixelfed GitHub
• ActivityPub Specification
• Laravel Horizon Documentation