Skip to content

Latest commit

 

History

History
440 lines (334 loc) · 8.37 KB

DEPLOYMENT.md

File metadata and controls

440 lines (334 loc) · 8.37 KB

N8N Workflows Documentation Platform - Deployment Guide

This guide covers deploying the N8N Workflows Documentation Platform in various environments.

Quick Start (Docker)

Development Environment

# Clone repository
git clone <repository-url>
cd n8n-workflows-1

# Start development environment
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

Production Environment

# Production deployment
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build

# With monitoring
docker compose --profile monitoring up -d

Deployment Options

1. Docker Compose (Recommended)

Development

# Start development environment with auto-reload
docker compose -f docker-compose.yml -f docker-compose.dev.yml up

# With additional dev tools (DB admin, file watcher)
docker compose --profile dev-tools up

Production

# Basic production deployment
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# With reverse proxy and SSL
docker compose --profile production up -d

# With monitoring stack
docker compose --profile monitoring up -d

2. Standalone Docker

# Build image
docker build -t workflows-doc:latest .

# Run container
docker run -d \
  --name n8n-workflows-docs \
  -p 8000:8000 \
  -v $(pwd)/database:/app/database \
  -v $(pwd)/logs:/app/logs \
  -e ENVIRONMENT=production \
  workflows-doc:latest

3. Python Direct Deployment

Prerequisites

  • Python 3.11+
  • pip

Installation

# Install dependencies
pip install -r requirements.txt

# Development mode
python run.py --dev

# Production mode
python run.py --host 0.0.0.0 --port 8000

Production with Gunicorn

# Install gunicorn
pip install gunicorn

# Start with gunicorn
gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 api_server:app

4. Kubernetes Deployment

Basic Deployment

# Apply Kubernetes manifests
kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml
kubectl apply -f k8s/ingress.yaml

Helm Chart

# Install with Helm
helm install n8n-workflows-docs ./helm/workflows-docs

Environment Configuration

Environment Variables

Variable Description Default Required
ENVIRONMENT Deployment environment development No
LOG_LEVEL Logging level info No
HOST Bind host 127.0.0.1 No
PORT Bind port 8000 No
DATABASE_PATH SQLite database path database/workflows.db No
WORKFLOWS_PATH Workflows directory workflows No
ENABLE_METRICS Enable Prometheus metrics false No
MAX_WORKERS Max worker processes 1 No
DEBUG Enable debug mode false No
RELOAD Enable auto-reload false No

Configuration Files

Create environment-specific configuration:

.env (Development)

ENVIRONMENT=development
LOG_LEVEL=debug
DEBUG=true
RELOAD=true

.env.production (Production)

ENVIRONMENT=production
LOG_LEVEL=warning
ENABLE_METRICS=true
MAX_WORKERS=4

Security Configuration

1. Reverse Proxy Setup (Traefik)

# traefik/config/dynamic.yml
http:
  middlewares:
    auth:
      basicAuth:
        users:
          - "admin:$2y$10$..."  # Generate with htpasswd
    security-headers:
      headers:
        customRequestHeaders:
          X-Forwarded-Proto: "https"
        customResponseHeaders:
          X-Frame-Options: "DENY"
          X-Content-Type-Options: "nosniff"
        sslRedirect: true

2. SSL/TLS Configuration

Let's Encrypt (Automatic)

# In docker-compose.prod.yml
command:
  - "--certificatesresolvers.myresolver.acme.tlschallenge=true"
  - "--certificatesresolvers.myresolver.acme.email=admin@yourdomain.com"

Custom SSL Certificate

volumes:
  - ./ssl:/ssl:ro

3. Basic Authentication

# Generate htpasswd entry
htpasswd -nb admin yourpassword

# Add to Traefik labels
- "traefik.http.middlewares.auth.basicauth.users=admin:$$2y$$10$$..."

Performance Optimization

1. Resource Limits

# docker-compose.prod.yml
deploy:
  resources:
    limits:
      memory: 512M
      cpus: '0.5'
    reservations:
      memory: 256M
      cpus: '0.25'

2. Database Optimization

# Force reindex for better performance
python run.py --reindex

# Or via API
curl -X POST http://localhost:8000/api/reindex

3. Caching Headers

# Traefik middleware for static files
http:
  middlewares:
    cache-headers:
      headers:
        customResponseHeaders:
          Cache-Control: "public, max-age=31536000"

Monitoring & Logging

1. Health Checks

# Docker health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/api/stats || exit 1

# Manual health check
curl http://localhost:8000/api/stats

2. Logs

# View application logs
docker compose logs -f workflows-docs

# View specific service logs
docker logs n8n-workflows-docs

# Log location in container
/app/logs/app.log

3. Metrics (Prometheus)

# Start monitoring stack
docker compose --profile monitoring up -d

# Access Prometheus
http://localhost:9090

Backup & Recovery

1. Database Backup

# Backup SQLite database
cp database/workflows.db database/workflows.db.backup

# Or using docker
docker exec n8n-workflows-docs cp /app/database/workflows.db /app/database/workflows.db.backup

2. Configuration Backup

# Backup entire configuration
tar -czf n8n-workflows-backup-$(date +%Y%m%d).tar.gz \
  database/ \
  logs/ \
  docker-compose*.yml \
  .env*

3. Restore

# Stop services
docker compose down

# Restore database
cp database/workflows.db.backup database/workflows.db

# Start services
docker compose up -d

Scaling & Load Balancing

1. Multiple Instances

# docker-compose.scale.yml
services:
  workflows-docs:
    deploy:
      replicas: 3
# Scale up
docker compose up --scale workflows-docs=3

2. Load Balancer Configuration

# Traefik load balancing
labels:
  - "traefik.http.services.workflows-docs.loadbalancer.server.port=8000"
  - "traefik.http.services.workflows-docs.loadbalancer.sticky=true"

Troubleshooting

Common Issues

  1. Database locked error

    # Check file permissions
ls -la database/

# Fix permissions
chmod 664 database/workflows.db

  2. Port already in use

    # Check what's using the port
lsof -i :8000

# Use different port
docker compose up -d -p 8001:8000

  3. Out of memory

    # Check memory usage
docker stats

# Increase memory limit
# Edit docker-compose.prod.yml resources

Logs & Debugging

# Application logs
docker compose logs -f workflows-docs

# System logs
docker exec workflows-docs tail -f /app/logs/app.log

# Database logs
docker exec workflows-docs sqlite3 /app/database/workflows.db ".tables"

Migration & Updates

1. Update Application

# Pull latest changes
git pull origin main

# Rebuild and restart
docker compose down
docker compose up -d --build

2. Database Migration

# Backup current database
cp database/workflows.db database/workflows.db.backup

# Force reindex with new schema
python run.py --reindex

3. Zero-downtime Updates

# Blue-green deployment
docker compose -p n8n-workflows-green up -d --build

# Switch traffic (update load balancer)
# Verify new deployment
# Shut down old deployment
docker compose -p n8n-workflows-blue down

Security Checklist

  • Use non-root user in Docker container
  • Enable HTTPS/SSL in production
  • Configure proper firewall rules
  • Use strong authentication credentials
  • Regular security updates
  • Enable access logs and monitoring
  • Backup sensitive data securely
  • Review and audit configurations regularly

Support & Maintenance

Regular Tasks

  1. Daily

    • Monitor application health
    • Check error logs
    • Verify backup completion

  2. Weekly

    • Review performance metrics
    • Update dependencies if needed
    • Test disaster recovery procedures

  3. Monthly

    • Security audit
    • Database optimization
    • Update documentation