add source code and readme
This commit is contained in:
246
manifests/applications/pixelfed/README.md
Normal file
246
manifests/applications/pixelfed/README.md
Normal file
@@ -0,0 +1,246 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user