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

# 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:

# 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

# 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

# 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
• Container Build Guide
• Infrastructure Setup