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

# PieFed - Reddit-like Fediverse Platform

PieFed is a Reddit-like platform that implements the ActivityPub protocol for federation. This deployment provides a complete PieFed instance optimized for the Keyboard Vagabond community.

## 🎯 **Access Information**

- **URL**: `https://piefed.keyboardvagabond.com`
- **Federation**: ActivityPub enabled, federated with other fediverse instances
- **Estimate User Limit**: 200 Monthly Active Users

## 🏗️ **Architecture**

### **Multi-Container Design**
- **Web Container**: Nginx + Django/uWSGI for HTTP requests
- **Worker Container**: Celery + Beat 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 with auto-scaling (2-6 replicas)
- **Worker**: 1 CPU core, 2GB RAM with auto-scaling (1-4 replicas)
- **Storage**: 10GB app storage + 5GB cache

## 📁 **File Structure**

```
manifests/applications/piefed/
├── namespace.yaml           # piefed-application namespace
├── secret.yaml             # Environment variables and credentials
├── harbor-pull-secret.yaml # Harbor registry authentication
├── storage.yaml             # Persistent volumes for app and cache
├── deployment-web.yaml      # Web server deployment with HPA
├── deployment-worker.yaml   # Background worker deployment with HPA
├── service.yaml             # Internal service for web pods
├── ingress.yaml             # External access with SSL
├── cronjobs.yaml           # Maintenance CronJobs
├── 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`
- **Database**: `piefed`
- **User**: `piefed_user`

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

### **S3 Media Storage**
- **Provider**: Backblaze B2
- **Bucket**: `piefed-bucket`
- **CDN**: `https://pfm.keyboardvagabond.com`
- **Region**: `eu-central-003`

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

## 🚀 **Deployment**

### **Prerequisites**
1. **Database Setup**: ✅ Database and user already created
2. **Secrets**: Update `secret.yaml` with:
   - Django SECRET_KEY (generate with `python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'`)
   - Admin password

### **Generate Required Secrets**
```bash
# Generate Django secret key
python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'

# Edit the secret with actual values
sops manifests/applications/piefed/secret.yaml
```

### **Deploy PieFed**
```bash
# Add piefed to applications kustomization
# manifests/applications/kustomization.yaml:
# resources:
# - piefed/

# Deploy all manifests
kubectl apply -k manifests/applications/piefed/

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

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

### **Post-Deployment Setup**
```bash
# Check deployment status
kubectl get pods -n piefed-application

# Check web container logs
kubectl logs -f deployment/piefed-web -n piefed-application

# Check worker container logs
kubectl logs -f deployment/piefed-worker -n piefed-application

# Access admin interface (if configured)
open https://piefed.keyboardvagabond.com/admin/
```

## 🔄 **Maintenance**

### **Automated CronJobs**
- **Daily Maintenance**: Session cleanup, upload cleanup (2 AM UTC daily)
- **Orphan File Removal**: Clean up orphaned media files (3 AM UTC Sunday)
- **Queue Processing**: Send queued notifications (every 10 minutes)

### **Manual Maintenance**
```bash
# Access web container for manual tasks
kubectl exec -it deployment/piefed-web -n piefed-application -- /bin/sh

# Run Django management commands
python manage.py migrate
python manage.py collectstatic
python manage.py createsuperuser
```

## 🔍 **Monitoring & Troubleshooting**

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

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

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

# Check auto-scaling
kubectl get hpa -n piefed-application
```

# Check celery queue length
```
kubectl exec -n redis-system redis-master-0 -- redis-cli -a <redis password> -n 0 llen celery
```

### **Database Connectivity**
```bash
# Test database connection
kubectl exec -it deployment/piefed-web -n piefed-application -- python manage.py dbshell
```

### **OpenObserve Integration**
- **ServiceMonitor**: Automatically configures metrics collection
- **Dashboards**: Available at `https://obs.keyboardvagabond.com`
- **Metrics**: Application performance, request rates, error rates

## 🎯 **Federation & Features**

### **ActivityPub Federation**
- Compatible with Mastodon, Lemmy, and other ActivityPub platforms
- Automatic content federation and user discovery
- Local and federated timelines

### **Reddit-like Features**
- Communities (similar to subreddits)
- Voting system (upvotes/downvotes)
- Threaded comments
- Moderation tools

## 📊 **Performance Optimization**

### **Auto-Scaling Configuration**
- **Web HPA**: 2-6 replicas based on CPU (70%) and memory (80%)
- **Worker HPA**: 1-4 replicas based on CPU (75%) and memory (85%)

### **Storage Optimization**
- **Longhorn Storage**: 2-replica redundancy with S3 backup
- **CDN**: Cloudflare CDN for static assets and media

## 🔗 **Integration with Infrastructure**

### **Perfect Fit For Your Setup**
- ✅ **PostgreSQL**: Uses your CloudNativePG cluster
- ✅ **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
- ✅ **Container Registry**: Uses Harbor for private image storage

---

**Built with ❤️ for your sophisticated Kubernetes infrastructure**