[Issue]: Write production deployment documentation

[dawidurbanski]

[Issue]: Write Production Deployment Documentation

Parent Epic: #57 - UDL as Production Data Layer
Phase: 6 - Documentation
Estimated Time: 1 day

Summary

Write comprehensive documentation for deploying UDL as a production data layer, covering common platforms (Vercel, Railway, Docker, VPS) and configuration best practices.

Context from Epic

The epic identifies documentation as MEDIUM priority:

Deployment Guide: Docs for running in production

The deployment guide should cover the epic's vision: deploying UDL as a durable, webhook-driven data cache that build workers and production apps consume.

Technical Specification

Scope

• Production deployment guide for common platforms
• Environment variable configuration
• Webhook endpoint setup with external services
• Health check configuration
• Scaling considerations

Documentation Structure

docs/content/4.deployment/
├── 1.production-overview.md     # Overview and architecture
├── 2.docker.md                   # Docker deployment
├── 3.vercel.md                   # Vercel/serverless deployment
├── 4.railway.md                  # Railway PaaS deployment
├── 5.vps.md                      # Traditional VPS deployment
└── 6.webhook-setup.md            # Configuring external webhooks

Content Outline

1. Production Overview

• Architecture diagram (from epic)
• When to use production UDL vs local-only
• Configuration options (remote field)
• Security considerations

2. Docker Deployment

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
RUN npm run build
EXPOSE 4000
HEALTHCHECK --interval=30s --timeout=10s \
  CMD curl -f http://localhost:4000/health || exit 1
CMD ["npm", "start"]

3. Vercel Deployment

• Using Vercel's serverless functions
• Environment variable setup
• Deploy hooks for rebuilds
• Limitations of serverless

4. Railway Deployment

• One-click deploy configuration
• Environment setup
• Persistent storage for cache

5. VPS Deployment

• systemd service configuration
• nginx reverse proxy
• SSL/TLS with Let's Encrypt
• Process management (PM2)

6. Webhook Setup

• Contentful webhook configuration
• Shopify webhook configuration
• Verifying webhook signatures
• Debugging webhook issues

Files to Create

• docs/content/4.deployment/1.production-overview.md
• docs/content/4.deployment/2.docker.md
• docs/content/4.deployment/3.vercel.md
• docs/content/4.deployment/4.railway.md
• docs/content/4.deployment/5.vps.md
• docs/content/4.deployment/6.webhook-setup.md

Implementation Tasks

• Create docs/content/4.deployment/ directory structure
• Write production overview with architecture diagram
• Write Docker deployment guide with Dockerfile
• Write Vercel deployment guide
• Write Railway deployment guide
• Write VPS deployment guide with systemd/nginx
• Write webhook setup guide for Contentful/Shopify
• Add navigation links in docs sidebar
• Review for completeness and accuracy

Acceptance Criteria

• All 6 documentation pages are complete
• Docker deployment guide includes working Dockerfile
• Each platform guide is tested and accurate
• Webhook setup guide covers common data sources
• Documentation follows existing docs style
• Health check configuration is documented
• Environment variables are documented
• No broken links

Dependencies

• Blocked by: [Issue]: Add health check endpoints #58 (health checks), [Issue]: Implement graceful shutdown #59 (graceful shutdown), [Issue]: Add plugin webhook registration API #60-63 (webhooks)
• Blocks: None
• Related: [Epic]: UDL as Production Data Layer #57 (parent epic)

Definition of Done

• Documentation complete and reviewed
• Examples tested and working
• PR reviewed and merged

Notes

• Focus on "< 5 min to deploy" goal from epic
• Include copy-paste ready configurations
• Add troubleshooting sections for common issues
• Reference the epic's architecture diagram