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

# BookWyrm - Social Reading Platform

BookWyrm is a decentralized social reading platform that implements the ActivityPub protocol for federation. This deployment provides a complete BookWyrm instance optimized for the Keyboard Vagabond community.

## 🎯 **Access Information**

- **URL**: `https://bookwyrm.keyboardvagabond.com`
- **Federation**: ActivityPub enabled, federated with other fediverse instances
- **Registration**: Open registration with email verification
- **User Target**: 200 Monthly Active Users (estimate support for up to 800)

## 🏗️ **Architecture**

### **Multi-Container Design**
- **Web Container**: Nginx + Django/Gunicorn for HTTP requests
- **Worker Container**: Celery + Beat for background jobs and federation
- **Database**: PostgreSQL (shared cluster with HA)
- **Cache**: Redis (shared cluster with dual databases)
- **Storage**: Backblaze B2 S3 + Cloudflare CDN
- **Mail**: SMTP

### **Resource Allocation**
- **Web**: 0.5-2 CPU cores, 1-4GB RAM (optimized for cluster capacity)
- **Worker**: 0.25-1 CPU cores, 512Mi-2GB RAM (background tasks)
- **Storage**: 10GB app storage + 5GB cache + 20GB backups

## 📁 **File Structure**

```
manifests/applications/bookwyrm/
├── namespace.yaml           # bookwyrm-application namespace
├── configmap.yaml           # Non-sensitive configuration (connections, settings)
├── secret.yaml              # SOPS-encrypted sensitive data (passwords, keys)
├── storage.yaml             # Persistent volumes for app, cache, and backups
├── 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 Zero Trust
├── 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**: `bookwyrm`
- **User**: `bookwyrm_user`

### **Redis Configuration**
- **Broker**: `redis-ha-haproxy.redis-system.svc.cluster.local` (DB 3)
- **Activity**: `redis-ha-haproxy.redis-system.svc.cluster.local` (DB 4)  
- **Cache**: `redis-ha-haproxy.redis-system.svc.cluster.local` (DB 5)

### **S3 Storage Configuration**
- **Provider**: Backblaze B2 S3-compatible storage
- **Bucket**: `bookwyrm-bucket`
- **CDN**: `https://bm.keyboardvagabond.com`
- **Region**: `eu-central-003`

### **Email Configuration**
- **Provider**: SMTP
- **From**: `<YOUR_EMAIL_ADDRESS>`
- **SMTP**: `<YOUR_SMTP_SERVER>:587`

## 🚀 **Deployment**

### **Prerequisites**
1. **PostgreSQL**: Database `bookwyrm` and user `bookwyrm_user` created
2. **Redis**: Available with databases 3, 4, and 5 for BookWyrm
3. **S3 Bucket**: `bookwyrm-bucket` configured in Backblaze B2
4. **CDN**: Cloudflare CDN configured for `bm.keyboardvagabond.com`
5. **Harbor**: Container images built and pushed

### **Deploy BookWyrm**
```bash
# Apply all manifests
kubectl apply -k manifests/applications/bookwyrm/

# Check deployment status
kubectl get pods -n bookwyrm-application

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

# View logs
kubectl logs -n bookwyrm-application deployment/bookwyrm-web
kubectl logs -n bookwyrm-application deployment/bookwyrm-worker
```

### **Initialize BookWyrm**
After deployment, initialize the database and create an admin user:
```bash
# Get web pod name
WEB_POD=$(kubectl get pods -n bookwyrm-application -l component=web -o jsonpath='{.items[0].metadata.name}')

# Initialize database (if needed)
kubectl exec -n bookwyrm-application $WEB_POD -- python manage.py initdb

# Create admin user
kubectl exec -it -n bookwyrm-application $WEB_POD -- python manage.py createsuperuser

# Collect static files
kubectl exec -n bookwyrm-application $WEB_POD -- python manage.py collectstatic --noinput

# Compile themes
kubectl exec -n bookwyrm-application $WEB_POD -- python manage.py compile_themes
```

## 🔐 **Zero Trust Configuration**

### **Cloudflare Zero Trust Setup**
1. **Add Hostname**: `bookwyrm.keyboardvagabond.com` in Zero Trust dashboard
2. **Service**: HTTP, `bookwyrm-web.bookwyrm-application.svc.cluster.local:80`
3. **Access Policy**: Configure as needed for your security requirements

### **Security Features**
- **HTTPS**: Enforced via Cloudflare edge
- **Headers**: Security headers via Cloudflare and NGINX ingress
- **S3**: Media storage with CDN distribution
- **Secrets**: SOPS-encrypted in Git
- **Network**: No external ports exposed (Zero Trust only)

## 📊 **Monitoring**

### **OpenObserve Integration**
Metrics automatically collected via ServiceMonitor:
- **URL**: `https://obs.keyboardvagabond.com`
- **Metrics**: BookWyrm application metrics, HTTP requests, response times
- **Logs**: Application logs via OpenTelemetry collector

### **Health Checks**
```bash
# Check pod status
kubectl get pods -n bookwyrm-application

# Check ingress and certificates
kubectl get ingress -n bookwyrm-application

# Check logs
kubectl logs -n bookwyrm-application deployment/bookwyrm-web
kubectl logs -n bookwyrm-application deployment/bookwyrm-worker

# Check HPA status
kubectl get hpa -n bookwyrm-application
```

## 🔧 **Troubleshooting**

### **Common Issues**
1. **Database Connection**: Ensure PostgreSQL cluster is running and database exists
2. **Redis Connection**: Verify Redis is accessible and databases 3-5 are available
3. **S3 Access**: Check Backblaze B2 credentials and bucket permissions
4. **Email**: Verify SMTP credentials and settings

### **Debug Commands**
```bash
# Check environment variables
kubectl exec -n bookwyrm-application deployment/bookwyrm-web -- env | grep -E "DB_|REDIS_|S3_"

# Test database connection
kubectl exec -n bookwyrm-application deployment/bookwyrm-web -- python manage.py check --database default

# Test Redis connection
kubectl exec -n bookwyrm-application deployment/bookwyrm-web -- python -c "import redis; r=redis.from_url('${REDIS_BROKER_URL}'); print(r.ping())"

# Check Celery workers
kubectl exec -n bookwyrm-application deployment/bookwyrm-worker -- celery -A celerywyrm inspect active
```

## 🎨 **Features**

- **Book Tracking**: Add books to shelves, rate and review
- **Social Features**: Follow users, see activity feeds
- **ActivityPub Federation**: Connect with other BookWyrm instances
- **Import/Export**: Import from Goodreads, LibraryThing, etc.
- **Book Data**: Automatic metadata fetching from multiple sources
- **Reading Goals**: Set and track annual reading goals
- **Book Clubs**: Create and join reading groups
- **Lists**: Create custom book lists and recommendations

## 🔗 **Related Documentation**

- [BookWyrm Official Documentation](https://docs.joinbookwyrm.com/)
- [Container Build Guide](../../../build/bookwyrm/README.md)
- [Infrastructure Setup](../../infrastructure/)