metabuilder/docs/architecture/deployment.md

Deployment Guide

Complete guide for deploying MetaBuilder to various environments.

📋 Prerequisites

• Node.js 18+
• Docker (for containerized deployment)
• npm or yarn
• Database access (SQLite for dev, PostgreSQL for production)

🚀 Deployment Options

1. Local Development

npm install
npm run db:generate
npm run db:push
npm run dev

Runs on http://localhost:5173.

2. Docker Development

docker-compose -f deployment/docker-compose.development.yml up

Features:

• Hot-reload on code changes
• Database mounted as volume
• Port 5173 mapped

3. Docker Production

docker-compose -f deployment/docker-compose.production.yml up -d

Features:

• Optimized build
• Production environment variables
• Health checks
• Auto-restart on failure

4. Cloud Deployment

Supports:

• AWS - EC2, ECS, Elastic Beanstalk
• Google Cloud - App Engine, Cloud Run
• Azure - App Service, Container Instances
• Heroku - Push to deploy
• DigitalOcean - Droplets or App Platform

🔧 Environment Configuration

Development (.env.local)

VITE_API_URL=http://localhost:3000
DATABASE_URL=file:./dev.db
NODE_ENV=development

Production (.env.production)

VITE_API_URL=https://api.example.com
DATABASE_URL=postgresql://user:pass@host/db
NODE_ENV=production
SECURE=true

Environment Variables

Variable	Purpose	Required
DATABASE_URL	Database connection string	✅ Yes
VITE_API_URL	API base URL	✅ Yes
NODE_ENV	Environment (dev/prod)	✅ Yes
SECRET_KEY	Application secret	✅ Yes
SECURE	Enable HTTPS	❌ No

🗄️ Database Setup

SQLite (Development)

npm run db:push

PostgreSQL (Production)

# Set connection string
export DATABASE_URL="postgresql://user:password@localhost:5432/metabuilder"

# Run migrations
npm run db:push

# Verify setup
npm run db:studio

🐳 Docker Configuration

Build Custom Image

docker build -f deployment/Dockerfile.app -t metabuilder:latest .
docker run -p 3000:3000 metabuilder:latest

Docker Compose

Development:

version: '3'
services:
  app:
    build:
      dockerfile: Dockerfile.app.dev
    ports:
      - "5173:5173"
    volumes:
      - .:/app
      - /app/node_modules

Production:

version: '3'
services:
  app:
    image: metabuilder:latest
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
      DATABASE_URL: postgresql://...
    healthcheck:
      test: curl -f http://localhost:3000/health
      interval: 30s
      timeout: 10s
      retries: 3

🔐 Security Checklist

Before production deployment:

• ✅ Use HTTPS (SSL/TLS certificates)
• ✅ Set strong database passwords
• ✅ Configure environment variables
• ✅ Enable database backups
• ✅ Set up monitoring & logging
• ✅ Configure firewall rules
• ✅ Enable rate limiting
• ✅ Set up admin users with strong passwords
• ✅ Review security documentation
• ✅ Test disaster recovery

📊 Health Monitoring

Health Check Endpoint

curl http://localhost:3000/health

Returns:

{
  "status": "ok",
  "database": "connected",
  "uptime": 3600
}

Logs

Docker logs:

docker logs metabuilder
docker logs -f metabuilder  # Follow logs

📈 Scaling Considerations

Horizontal Scaling

Multiple instances behind load balancer:

┌─────────┐
│ Nginx   │ (Load Balancer)
└────┬────┘
     │
  ┌──┴──┬──────┬──────┐
  │     │      │      │
┌─┴─┐ ┌─┴─┐ ┌─┴─┐ ┌─┴─┐
│App│ │App│ │App│ │App│
└─┬─┘ └─┬─┘ └─┬─┘ └─┬─┘
  │     │     │     │
  └─────┴─────┴─────┘
         │
     ┌───┴────┐
    Database (shared)

Database Optimization

• Use PostgreSQL connection pooling
• Enable query caching
• Monitor slow queries
• Regular backups

🔄 Continuous Deployment

GitHub Actions Workflow

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: npm install
      - run: npm run lint
      - run: npm run test:e2e
      - run: npm run build
      - run: docker push metabuilder:latest

📊 Monitoring & Logging

Essential Metrics

• Application uptime
• Response times
• Error rates
• Database performance
• User activity

Log Aggregation

Consider:

• CloudWatch (AWS)
• Stackdriver (Google Cloud)
• Application Insights (Azure)
• ELK Stack (self-hosted)

🆘 Troubleshooting

Common Issues

Database connection fails

# Check DATABASE_URL
echo $DATABASE_URL

# Test connection
npm run db:studio

Port already in use

# Find process on port 3000
lsof -i :3000

# Kill process
kill -9 <PID>

Out of memory

# Increase Node.js heap
export NODE_OPTIONS="--max-old-space-size=4096"

📚 Additional Resources

• Docker Documentation
• PostgreSQL Documentation
• Prisma Deployment
• GitHub Actions

🔗 Related Documentation

• Getting Started
• Database Architecture TODO: Security guide lives at ../security/SECURITY.md; update this link.
• Security Guidelines
• Architecture Overview