fix: add S3 storage env vars to rest-api, hocuspocus, and worker services

Author: HMarzban

DEPLOYMENT.md

@@ -0,0 +1,226 @@
+# Deployment Guide - Traefik Architecture
+
+## Architecture
+
+```
+Internet → Traefik (SSL/LB, ports 80/443) → Docker Services
+```
+
+**Services:**
+
+- `webapp` (Next.js) - docs.plus
+- `rest-api` - prodback.docs.plus/api/\*
+- `hocuspocus-server` - prodback.docs.plus/hocuspocus/\*
+- `hocuspocus-worker` - background jobs
+- `redis` - cache & pub/sub
+- `traefik` - reverse proxy + auto SSL
+
+## Quick Start
+
+### Prerequisites
+
+```bash
+# Server requirements
+- Docker 24+
+- Docker Compose 2.20+
+- Open ports: 80, 443
+```
+
+### 1. First-time Server Setup
+
+```bash
+# Create directories
+sudo mkdir -p /opt/projects/prod.docs.plus
+cd /opt/projects/prod.docs.plus
+
+# Create .env file
+cat > .env << 'EOF'
+# Database (DigitalOcean managed)
+DATABASE_URL=postgresql://user:pass@host:25060/db?sslmode=require
+
+# Supabase
+SUPABASE_URL=https://xxx.supabase.co
+SUPABASE_ANON_KEY=eyJ...
+SUPABASE_SERVICE_ROLE_KEY=eyJ...
+
+# Next.js public vars
+NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
+NEXT_PUBLIC_PROVIDER_URL=wss://prodback.docs.plus/hocuspocus
+NEXT_PUBLIC_RESTAPI_URL=https://prodback.docs.plus/api
+
+# Auth
+JWT_SECRET=your-jwt-secret-min-32-chars
+
+# Traefik
+[email protected]
+TRAEFIK_DASHBOARD_AUTH=admin:$apr1$xyz$hash  # htpasswd -nb admin password
+
+# Misc
+ALLOWED_ORIGINS=https://docs.plus
+EOF
+
+# Setup GitHub Actions runner
+mkdir -p app/docs.plus
+cd app/docs.plus
+# Configure self-hosted runner: Settings → Actions → Runners → New
+```
+
+### 2. DNS Setup
+
+Point these domains to your server IP:
+
+- `docs.plus` → Server IP
+- `prodback.docs.plus` → Server IP
+- `traefik.docs.plus` → Server IP (optional, for dashboard)
+- `status.docs.plus` → Server IP (optional, for uptime kuma)
+
+### 3. Deploy
+
+Push to main with commit message containing `build front` or `build back`:
+
+```bash
+git commit --allow-empty -m "build front back"
+git push
+```
+
+## Manual Deployment
+
+```bash
+# From server
+cd /opt/projects/prod.docs.plus/app/docs.plus/docs.plus
+
+# Deploy
+docker-compose -f docker-compose.prod.yml \
+  --env-file /opt/projects/prod.docs.plus/.env \
+  up -d --build \
+  --scale webapp=2 \
+  --scale rest-api=2 \
+  --scale hocuspocus-server=2
+
+# View logs
+docker-compose -f docker-compose.prod.yml logs -f
+
+# Check status
+docker ps
+```
+
+## Scaling
+
+```bash
+# Scale services
+docker-compose -f docker-compose.prod.yml up -d \
+  --scale webapp=4 \
+  --scale rest-api=4 \
+  --scale hocuspocus-server=4
+
+# Traefik auto-balances traffic
+```
+
+## Monitoring
+
+### View logs
+
+```bash
+# All services
+docker-compose -f docker-compose.prod.yml logs -f
+
+# Specific service
+docker logs -f <container-name>
+```
+
+### Health endpoints
+
+```bash
+curl https://docs.plus/api/health
+curl https://prodback.docs.plus/api/health
+curl https://prodback.docs.plus/hocuspocus/health
+```
+
+### Traefik Dashboard
+
+Access at `https://traefik.docs.plus` (requires auth)
+
+## Rollback
+
+```bash
+# Find previous image
+docker images docsy-webapp --format "{{.Tag}}"
+
+# Rollback to previous tag
+export DEPLOY_TAG=<previous-tag>
+docker-compose -f docker-compose.prod.yml \
+  --env-file /opt/projects/prod.docs.plus/.env \
+  up -d
+```
+
+## Troubleshooting
+
+### SSL not working
+
+```bash
+# Check Traefik logs
+docker logs traefik
+
+# SSL certs stored in volume
+docker volume inspect docsplus_traefik-certs
+
+# Force cert renewal
+docker exec traefik traefik healthcheck
+```
+
+### Service not accessible
+
+```bash
+# Check if Traefik sees the service
+docker exec traefik traefik healthcheck
+
+# Check container labels
+docker inspect <container> | jq '.[0].Config.Labels'
+
+# Verify network
+docker network inspect docsplus-network
+```
+
+### Container keeps restarting
+
+```bash
+# Check logs
+docker logs <container> --tail 100
+
+# Common issues:
+# - DATABASE_URL wrong → check .env
+# - Redis not ready → check redis container
+# - Build args missing → rebuild with --no-cache
+```
+
+## Environment Variables
+
+| Variable                    | Description                             |
+| --------------------------- | --------------------------------------- |
+| `DATABASE_URL`              | PostgreSQL connection string (with SSL) |
+| `SUPABASE_URL`              | Supabase project URL                    |
+| `SUPABASE_ANON_KEY`         | Supabase anon key                       |
+| `SUPABASE_SERVICE_ROLE_KEY` | Supabase service role key               |
+| `JWT_SECRET`                | JWT signing secret (32+ chars)          |
+| `ACME_EMAIL`                | Email for Let's Encrypt certs           |
+| `TRAEFIK_DASHBOARD_AUTH`    | htpasswd auth for Traefik dashboard     |
+| `ALLOWED_ORIGINS`           | CORS allowed origins                    |
+| `NEXT_PUBLIC_*`             | Public vars baked into frontend         |
+
+## Useful Commands
+
+```bash
+# Restart all
+docker-compose -f docker-compose.prod.yml restart
+
+# Rebuild specific service
+docker-compose -f docker-compose.prod.yml up -d --build webapp
+
+# Force recreate
+docker-compose -f docker-compose.prod.yml up -d --force-recreate
+
+# Clean everything (WARNING: deletes data)
+docker-compose -f docker-compose.prod.yml down -v
+docker system prune -af
+```