create-lego-one 2.0.12 → 2.0.14

package/template/docs/framework/setup/13-deployment-guide.md

@@ -0,0 +1,566 @@
+# Deployment Guide
+
+**Production Deployment Instructions**
+
+---
+
+## Overview
+
+This guide covers deploying the Lego-One SaaS boilerplate to various platforms. Lego-One can be deployed as Docker containers, directly to cloud platforms, or via traditional hosting.
+
+---
+
+## Prerequisites
+
+Before deploying, ensure you have:
+
+- Node.js 20+ installed
+- pnpm package manager
+- Docker (for containerized deployment)
+- Git (for version control)
+- Domain name (for production)
+- SSL certificate (for HTTPS)
+
+---
+
+## Environment Setup
+
+### Environment Variables
+
+Create a `.env.production` file:
+
+```bash
+# PocketBase Configuration
+VITE_POCKETBASE_URL=https://pb.yourdomain.com
+
+# Application Configuration
+VITE_APP_NAME=Your App Name
+VITE_APP_URL=https://yourdomain.com
+
+# Plugin Configuration
+VITE_PLUGINS_ENABLED=true
+
+# Feature Flags
+VITE_ENABLE_DEVTOOLS=false
+VITE_ENABLE_ANALYTICS=true
+
+# External Services (Optional)
+VITE_SENTRY_DSN=https://your-sentry-dsn
+VITE_GA_ID=G-XXXXXXXXXX
+VITE_STRIPE_PUBLIC_KEY=pk_live_xxxxx
+```
+
+### Build Configuration
+
+Update `host/tsconfig.json` to exclude test files from production:
+
+```json
+{
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/__tests__",
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/*.spec.ts",
+    "**/*.spec.tsx",
+    "src/test"
+  ]
+}
+```
+
+---
+
+## Docker Deployment
+
+### Build Docker Image
+
+```bash
+docker build -t lego-one:latest .
+```
+
+### Run Container
+
+```bash
+docker run -d \
+  --name lego-one \
+  -p 80:80 \
+  -p 8090:8090 \
+  -v lego_pb_data:/data/pb \
+  -e VITE_POCKETBASE_URL=http://localhost:8090 \
+  lego-one:latest
+```
+
+### Docker Compose
+
+```bash
+# Start services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop services
+docker-compose down
+
+# Rebuild and restart
+docker-compose up -d --build
+```
+
+### Production Docker Compose
+
+Create `docker-compose.prod.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  app:
+    image: lego-one:latest
+    ports:
+      - "80:80"
+      - "8090:8090"
+    environment:
+      - VITE_POCKETBASE_URL=https://pb.yourdomain.com
+      - VITE_APP_NAME=Your App
+      - VITE_APP_URL=https://yourdomain.com
+      - VITE_ENABLE_DEVTOOLS=false
+    volumes:
+      - pb_data:/data/pb
+    restart: always
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://localhost/80"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+volumes:
+  pb_data:
+```
+
+---
+
+## Cloud Platforms
+
+### Vercel (Frontend Only)
+
+Deploy the host application and plugins to Vercel:
+
+```bash
+# Install Vercel CLI
+pnpm add -g vercel
+
+# Deploy
+vercel --prod
+```
+
+**vercel.json** configuration:
+
+```json
+{
+  "buildCommand": "pnpm run build",
+  "outputDirectory": "host/dist",
+  "rewrites": [
+    { "source": "/api/:path*", "destination": "https://pb.yourdomain.com/:path*" }
+  ]
+}
+```
+
+### Railway (Full Stack)
+
+1. Create a new project on Railway
+2. Connect your GitHub repository
+3. Configure environment variables
+4. Deploy
+
+**railway.json** configuration:
+
+```json
+{
+  "build": {
+    "builder": "NIXPACKS"
+  },
+  "deploy": {
+    "startCommand": "pnpm run start",
+    "healthcheckPath": "/"
+  }
+}
+```
+
+### Render (Full Stack)
+
+1. Create a new Web Service on Render
+2. Connect your GitHub repository
+3. Set build command: `pnpm run build`
+4. Set start command: `pnpm run start`
+5. Add environment variables
+6. Deploy
+
+### DigitalOcean App Platform
+
+1. Create a new app
+2. Choose your GitHub repository
+3. Configure build and run settings
+4. Add environment variables
+5. Deploy
+
+---
+
+## Production Checklist
+
+### Security
+
+- [ ] Environment variables are set (not using defaults)
+- [ ] HTTPS/SSL is enabled
+- [ ] CORS is properly configured
+- [ ] Rate limiting is enabled
+- [ ] Security headers are set
+- [ ] Database credentials are strong
+- [ ] API tokens are rotated
+- [ ] Sensitive data is encrypted
+
+### Performance
+
+- [ ] Static assets are cached
+- [ ] Gzip/brotli compression is enabled
+- [ ] Bundle size is optimized
+- [ ] Images are optimized
+- [ ] CDN is configured
+- [ ] Database queries are optimized
+- [ ] Caching strategy is implemented
+
+### Monitoring
+
+- [ ] Error tracking (Sentry) is configured
+- [ ] Analytics (Google Analytics) is set up
+- [ ] Logging is enabled
+- [ ] Health checks are configured
+- [ ] Uptime monitoring is active
+- [ ] Performance monitoring is set up
+
+### Backup
+
+- [ ] Database backups are scheduled
+- [ ] Backup restoration is tested
+- [ ] Disaster recovery plan is documented
+- [ ] Backups are stored off-site
+
+### Documentation
+
+- [ ] API documentation is up to date
+- [ ] Deployment runbook is written
+- [ ] On-call procedures are documented
+- [ ] Architecture diagrams are current
+
+---
+
+## Monitoring & Maintenance
+
+### Health Checks
+
+Create a health check endpoint:
+
+```typescript
+// host/src/routes/HealthPage.tsx
+export function HealthPage() {
+  return Response.json({
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+    uptime: process.uptime(),
+  });
+}
+```
+
+### Logging
+
+Use structured logging:
+
+```typescript
+// host/src/lib/logger.ts
+export const logger = {
+  info: (message: string, meta?: any) => {
+    console.log(JSON.stringify({ level: 'info', message, ...meta }));
+  },
+  error: (message: string, error?: Error) => {
+    console.error(JSON.stringify({
+      level: 'error',
+      message,
+      error: error?.stack,
+    }));
+  },
+};
+```
+
+### Error Tracking
+
+Set up Sentry:
+
+```typescript
+// host/src/sentry.ts
+import * as Sentry from '@sentry/react';
+
+Sentry.init({
+  dsn: import.meta.env.VITE_SENTRY_DSN,
+  environment: import.meta.env.MODE,
+  tracesSampleRate: 1.0,
+});
+```
+
+### Performance Monitoring
+
+Use Web Vitals:
+
+```typescript
+// host/src/lib/web-vitals.ts
+import { onCLS, onFID, onFCP, onLCP, onTTFB } from 'web-vitals';
+
+export function reportWebVitals() {
+  onCLS(console.log);
+  onFID(console.log);
+  onFCP(console.log);
+  onLCP(console.log);
+  onTTFB(console.log);
+}
+```
+
+---
+
+## Scaling Strategies
+
+### Horizontal Scaling
+
+Deploy multiple app instances behind a load balancer:
+
+```nginx
+upstream app {
+    server app1:80;
+    server app2:80;
+    server app3:80;
+}
+
+server {
+    location / {
+        proxy_pass http://app;
+    }
+}
+```
+
+### Database Scaling
+
+For high-traffic applications:
+
+1. **External PostgreSQL** - Replace SQLite with PostgreSQL
+2. **Connection Pooling** - Use PgBouncer
+3. **Read Replicas** - Offload read queries
+4. **Caching** - Add Redis for session/cache
+
+### Caching Strategy
+
+```typescript
+// Cache API responses
+const { data } = useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  staleTime: 5 * 60 * 1000, // 5 minutes
+  cacheTime: 10 * 60 * 1000, // 10 minutes
+});
+```
+
+---
+
+## CI/CD Pipeline
+
+### GitHub Actions
+
+Create `.github/workflows/deploy.yml`:
+
+```yaml
+name: Deploy
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 8
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run tests
+        run: pnpm test --run
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Deploy to production
+        run: ./scripts/deploy.sh production
+```
+
+---
+
+## Security Best Practices
+
+### Keep Dependencies Updated
+
+```bash
+pnpm update
+pnpm audit
+```
+
+### Use HTTPS Everywhere
+
+- Redirect HTTP to HTTPS
+- Use HSTS headers
+
+### Implement Rate Limiting
+
+```typescript
+// Rate limit API endpoints
+app.use('/api', rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100 // limit each IP to 100 requests per windowMs
+}));
+```
+
+### Sanitize User Input
+
+```typescript
+// Validate and sanitize input
+const schema = z.object({
+  title: z.string().max(200).transform(s => s.trim())
+});
+```
+
+### Implement CSRF Protection
+
+- Use SameSite cookies
+- Verify request origins
+
+---
+
+## Rollback Procedures
+
+### Quick Rollback
+
+```bash
+# Docker
+docker-compose down
+docker-compose up -d --build
+
+# Or revert to previous image
+docker tag lego-one:previous lego-one:latest
+docker-compose up -d
+```
+
+### Database Rollback
+
+```bash
+# Restore from backup
+docker cp backup/pb_data/ container:/data/pb/
+docker restart container
+```
+
+---
+
+## Troubleshooting
+
+### Build Issues
+
+**Problem:** Build fails with TypeScript errors
+
+**Solution:**
+```bash
+# Check TypeScript config
+pnpm run typecheck
+
+# Fix errors before building
+```
+
+### Runtime Issues
+
+**Problem:** App loads but PocketBase connection fails
+
+**Solution:**
+1. Check `VITE_POCKETBASE_URL` is correct
+2. Verify PocketBase is accessible
+3. Check CORS settings on PocketBase
+
+### Performance Issues
+
+**Problem:** Slow page load times
+
+**Solution:**
+1. Analyze bundle size
+2. Enable code splitting
+3. Optimize images
+4. Enable CDN
+
+---
+
+## Maintenance Tasks
+
+### Daily
+
+- Monitor error rates
+- Check system health
+- Review logs for issues
+
+### Weekly
+
+- Review analytics
+- Check backup integrity
+- Update dependencies
+
+### Monthly
+
+- Review and rotate secrets
+- Audit user access
+- Update documentation
+- Performance review
+
+### Quarterly
+
+- Security audit
+- Disaster recovery test
+- Architecture review
+- Cost optimization
+
+---
+
+## Cost Optimization
+
+### Right-Sizing Resources
+
+- Start with minimum resources
+- Scale based on actual usage
+- Use spot instances where possible
+
+### Database Optimization
+
+- Index frequently queried fields
+- Archive old data
+- Use connection pooling
+
+### CDN Usage
+
+- Cache static assets
+- Use CDN for API responses
+- Implement edge functions
+
+---
+
+**End of Deployment Guide**