188 lines
6.9 KiB
Markdown
188 lines
6.9 KiB
Markdown
# 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/)
|