n8n-compose/docs/DEPLOYMENT.md

Deployment Guide

Prerequisites

Before deploying to production, ensure the following are available:

• Docker & Docker Compose (v20.0+)
• Freescout API Key (from Freescout instance admin panel)
• Baramundi API Access (with valid credentials)
• PostgreSQL Database Server or Container capability
• Git access to Gitea repository
• n8n instance access credentials
• System resources: 4GB RAM minimum, 20GB storage

Architecture Overview

The deployment consists of:

• n8n: Workflow orchestration engine
• PostgreSQL: Database for audit logs and workflow state
• Milvus: Vector database for knowledge base embeddings
• Freescout: Helpdesk system (external integration)
• Baramundi: Asset management system (external integration)

Deployment Steps

1. Clone Repository from Gitea

git clone https://git.eks-intec.de/eksadmin/n8n-compose.git
cd n8n-compose

2. Setup Environment Variables

Copy the example configuration and update with production values:

cp .env.example .env

Edit .env and configure the following:

# n8n Configuration
N8N_HOST=your-n8n-domain.com
N8N_PROTOCOL=https
N8N_PORT=5678
N8N_ENCRYPTION_KEY=your-secure-encryption-key

# PostgreSQL Configuration
POSTGRES_USER=n8n_user
POSTGRES_PASSWORD=your-secure-postgres-password
POSTGRES_DB=n8n_production
POSTGRES_HOST=postgres

# Freescout Integration
FREESCOUT_API_KEY=your-freescout-api-key
FREESCOUT_HOST=https://your-freescout-instance.com
FREESCOUT_ACCOUNT_ID=1

# Baramundi Integration
BARAMUNDI_API_KEY=your-baramundi-api-key
BARAMUNDI_HOST=https://your-baramundi-instance.com
BARAMUNDI_API_ENDPOINT=/api/v1

# Milvus Vector Database
MILVUS_HOST=milvus
MILVUS_PORT=19530

# Monitoring
LOG_LEVEL=info
NODE_ENV=production

3. Prepare Database

Initialize the PostgreSQL audit schema:

docker-compose up -d postgres
sleep 5

# Run audit schema initialization
docker exec -i n8n-postgres psql -U n8n_user -d n8n_production < sql/01-audit-schema.sql

Verify schema creation:

docker exec n8n-postgres psql -U n8n_user -d n8n_production -c "\dt audit.*"

4. Run Docker Services

Start all services:

docker-compose up -d

Verify all services are running:

docker-compose ps

Expected output:

NAME                COMMAND             STATUS
n8n                 n8n start           Up (healthy)
postgres            postgres            Up (healthy)
milvus              milvus server       Up (healthy)

Wait for services to become healthy (typically 30-60 seconds):

docker-compose logs -f

5. Setup Freescout Custom Fields

The Freescout integration requires custom fields for workflow state tracking. Run the setup script:

bash scripts/setup-freescout-fields.sh

This script creates:

• ai_suggestion field: AI-generated ticket suggestions
• approval_status field: Approval workflow state (pending/approved/rejected)
• kb_reference field: Knowledge base article references

Verify fields in Freescout Admin > Custom Fields.

6. Import n8n Workflows

Access n8n at https://your-n8n-domain.com:5678

Option A: Manual Import via UI

1. Open n8n Dashboard
2. Click "Import" button
3. Select workflow JSON file from n8n-workflows/ directory
4. Confirm and save

Option B: Command Line Import

Workflows to import in order:

1. Workflow A: Mail Processing

   curl -X POST http://localhost:5678/api/v1/workflows \
     -H "X-N8N-API-KEY: $N8N_API_KEY" \
     -H "Content-Type: application/json" \
     -d @n8n-workflows/workflow-a-mail-processing.json
   

2. Workflow B: Approval Execution

   curl -X POST http://localhost:5678/api/v1/workflows \
     -H "X-N8N-API-KEY: $N8N_API_KEY" \
     -H "Content-Type: application/json" \
     -d @n8n-workflows/workflow-b-approval-execution.json
   

3. Workflow C: Knowledge Base Update

   curl -X POST http://localhost:5678/api/v1/workflows \
     -H "X-N8N-API-KEY: $N8N_API_KEY" \
     -H "Content-Type: application/json" \
     -d @n8n-workflows/workflow-c-kb-update.json
   

7. Run E2E Tests

Execute the comprehensive test suite:

bash tests/curl-test-collection.sh

Expected test results:

• Mail processing flow: PASS
• Approval workflow: PASS
• KB update cycle: PASS
• Baramundi integration: PASS
• Error handling: PASS

All tests must pass before proceeding to production activation.

8. Enable Workflows in Production

Once tests pass, activate all workflows:

1. Open n8n Dashboard

2. For each workflow (A, B, C):

   • Click workflow
   • Toggle "Active" switch ON
   • Confirm activation

3. Verify in logs:

   docker-compose logs -f n8n | grep "Workflow"
   

Expected log output:

n8n | [INFO] Workflow A (Mail Processing) activated
n8n | [INFO] Workflow B (Approval Execution) activated
n8n | [INFO] Workflow C (KB Update) activated

Monitoring and Verification

Health Checks

Monitor service health:

docker-compose ps
docker-compose logs -f n8n
docker-compose logs -f postgres

Database Verification

Check PostgreSQL audit tables:

docker exec n8n-postgres psql -U n8n_user -d n8n_production -c \
  "SELECT COUNT(*) FROM audit.workflow_executions;"

Workflow Execution Logs

View real-time workflow executions:

curl -H "X-N8N-API-KEY: $N8N_API_KEY" \
  http://localhost:5678/api/v1/executions?limit=10

For detailed monitoring setup, see docs/MONITORING.md.

Rollback Procedure

In case of critical issues, follow these rollback steps:

Immediate Action (Within 5 minutes)

1. Deactivate all workflows

   # Stop workflow execution
   docker-compose exec -T n8n n8n stop --timeout 30
   

2. Verify no ongoing operations

   docker-compose logs -f n8n | grep "execution"
   

3. Notify stakeholders

   • Send alert to team
   • Pause Freescout ticket processing
   • Document incident time

Rollback Steps (15-30 minutes)

1. Option A: Revert to Last Known Good State

   # Stop services
   docker-compose down
   
   # Restore database from backup
   docker-compose up -d postgres
   sleep 10
   psql -U n8n_user -d n8n_production < backups/pre-golive-backup.sql
   
   # Start other services
   docker-compose up -d n8n milvus
   

2. Option B: Complete Reset (if corruption suspected)

   # Remove all containers and data
   docker-compose down -v
   
   # Restore from last full backup
   docker-compose up -d postgres
   sleep 10
   psql -U n8n_user -d n8n_production < backups/full-restore.sql
   
   # Restart all services
   docker-compose up -d
   
   # Re-import workflows
   bash scripts/import-workflows.sh
   

3. Verify rollback success

   docker-compose ps
   curl http://localhost:5678/api/v1/health
   

Data Integrity Checks

# Check audit logs consistency
docker exec n8n-postgres psql -U n8n_user -d n8n_production -c \
  "SELECT status, COUNT(*) FROM audit.workflow_executions GROUP BY status;"

# Verify no orphaned records
docker exec n8n-postgres psql -U n8n_user -d n8n_production -c \
  "SELECT COUNT(*) FROM audit.workflow_executions WHERE workflow_id NOT IN
   (SELECT id FROM audit.workflows);"

Communication

After successful rollback:

1. Send all-clear notification
2. Schedule post-mortem meeting
3. Document root cause
4. Plan remediation

Troubleshooting

Service Startup Issues

n8n won't start:

docker-compose logs n8n
docker-compose up -d n8n --no-deps --build

PostgreSQL connection fails:

docker-compose exec postgres pg_isready
docker-compose logs postgres

Milvus vector DB issues:

docker-compose logs milvus
docker-compose restart milvus

Integration Issues

Freescout API authentication fails:

• Verify API key in .env
• Check Freescout API endpoint accessibility
• Test with curl: curl -H "Authorization: Bearer $FREESCOUT_API_KEY" https://freescout-host/api/v1/accounts

Baramundi connection problems:

• Verify credentials and endpoint
• Check network connectivity
• Test API: curl -H "Authorization: Bearer $BARAMUNDI_API_KEY" https://baramundi-host/api/v1/health

Performance Issues

High CPU/Memory usage:

docker stats
docker-compose logs -f n8n | grep "memory\|cpu"

Slow database queries:

# Enable query logging
docker-compose exec postgres psql -U n8n_user -d n8n_production -c \
  "ALTER SYSTEM SET log_statement = 'all';"
docker-compose restart postgres

Support and Documentation

• n8n Documentation: https://docs.n8n.io
• Docker Compose Reference: https://docs.docker.com/compose
• PostgreSQL Admin Guide: https://www.postgresql.org/docs/current/admin.html
• Additional setup details: See docs/ARCHITECTURE.md

Deployment Checklist

• All prerequisites installed and configured
• Repository cloned successfully
• .env file configured with production values
• PostgreSQL initialized with audit schema
• All Docker services running and healthy
• Freescout custom fields created
• All n8n workflows imported
• E2E test suite passed (100%)
• All workflows activated
• Monitoring configured and active
• Backup strategy in place
• Team trained on deployment and rollback

Once all items are checked, the system is ready for Go-Live.