Refactor code structure for improved readability and maintainability

DEPLOYMENT.md

@@ -0,0 +1,169 @@
+# Production Deployment Guide
+
+This guide describes a production-style deployment for Linear Void using Docker Compose, Gitea registry images, and Cloudflare fronting.
+
+## Target Topology
+
+- Host: Linux server with Docker Engine
+- Reverse proxy: nginx container (linearvoid-nginx)
+- Core services: playout, chat, redis, postgres
+- Observability: prometheus, grafana
+- CDN/edge: Cloudflare
+
+## Prerequisites
+
+- Docker Engine + Docker Compose plugin
+- Network access to git.allucanget.biz
+- A valid .env file with production values
+- DNS configured for linearvoid.tv (and media.linearvoid.tv if split media domain is used)
+
+## Environment File
+
+Use .env with at least:
+
+- CI_REGISTRY_URL
+- CI_REGISTRY_NAMESPACE
+- CHAT_PORT
+- NGINX_PORT
+- DATABASE_URL (if overridden)
+- REDIS_URL (if overridden)
+- ADMIN_USERNAME
+- ADMIN_PASSWORD
+- VITE_PUBLIC_APP_URL
+- VITE_PUBLIC_WS_URL
+- VITE_PUBLIC_HLS_URL
+- Cloudflare/R2 variables when media sync is enabled
+
+See .env.example and SETUP.md for full variable reference.
+
+## Pull-and-Run Deployment
+
+From repository root:
+
+```bash
+docker login git.allucanget.biz
+
+docker compose -f docker-compose.prod.yml pull
+docker compose -f docker-compose.prod.yml up -d --remove-orphans
+```
+
+## First-Time or Recovery Provisioning
+
+1. Ensure host paths exist:
+
+```bash
+mkdir -p data/chat data/playlist data/media data/hls
+```
+
+1. Confirm volumes and networks:
+
+```bash
+docker volume ls
+docker network ls
+```
+
+1. Start stack:
+
+```bash
+docker compose -f docker-compose.prod.yml up -d
+```
+
+## Health Verification
+
+After startup, check service status:
+
+```bash
+docker compose -f docker-compose.prod.yml ps
+```
+
+Endpoint checks:
+
+- App: <http://{host}:8080/>
+- Nginx health: <http://{host}:8080/health>
+- Chat health: <http://{host}:3000/health>
+- Playout health: <http://{host}:8081/health>
+- Prometheus: <http://{host}:9090>
+- Grafana: <http://{host}:3001>
+
+Domain checks:
+
+- <https://linearvoid.tv>
+- <https://linearvoid.tv/admin>
+- <https://linearvoid.tv/metrics>
+
+## Zero/Low-Downtime Update Pattern
+
+1. Pull newest images.
+1. Recreate changed services only:
+
+```bash
+docker compose -f docker-compose.prod.yml pull
+
+docker compose -f docker-compose.prod.yml up -d nginx chat playout
+```
+
+1. Re-run health checks.
+
+## Rollback
+
+If new images are unhealthy:
+
+1. Pin previous tags in docker-compose.prod.yml.
+2. Pull pinned tags.
+3. Restart impacted services.
+
+```bash
+docker compose -f docker-compose.prod.yml pull
+
+docker compose -f docker-compose.prod.yml up -d nginx chat playout
+```
+
+## Operational Tasks
+
+### View logs
+
+```bash
+docker compose -f docker-compose.prod.yml logs -f nginx chat playout
+```
+
+### Restart one service
+
+```bash
+docker compose -f docker-compose.prod.yml restart chat
+```
+
+### Stop stack
+
+```bash
+docker compose -f docker-compose.prod.yml down
+```
+
+### Keep volumes (recommended) vs remove volumes (destructive)
+
+```bash
+# keep data
+docker compose -f docker-compose.prod.yml down
+
+# destructive (remove data)
+docker compose -f docker-compose.prod.yml down -v
+```
+
+## Nginx and Proxy Considerations
+
+- If an external proxy (for example Nginx Proxy Manager) fronts the stack, align request body limits with internal nginx.
+- For resumable admin uploads, ensure client_max_body_size supports chunk requests in both proxy layers.
+
+## Security Baseline
+
+- Use strong ADMIN_PASSWORD and rotate regularly.
+- Keep Docker host access restricted.
+- Prefer HTTPS/WSS through Cloudflare.
+- Restrict exposed ports if only proxy access is needed.
+
+## Common Deployment Pitfalls
+
+- Missing frontend build artifacts in local-only compose workflows.
+- Wrong registry credentials or missing login.
+- Misaligned domain env vars (app/ws/hls) causing mixed-origin errors.
+- Proxy-layer body size limits returning 413 on upload.
+- Health checks failing before service warmup is complete.