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

```bash
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:

```bash
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:

```bash
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:

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

### 4. Run Docker Services

Start all services:

```bash
docker-compose up -d
```

Verify all services are running:

```bash
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):

```bash
docker-compose logs -f
```

### 5. Setup Freescout Custom Fields

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

```bash
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**
   ```bash
   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**
   ```bash
   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**
   ```bash
   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
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:
   ```bash
   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:

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

### Database Verification

Check PostgreSQL audit tables:

```bash
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:

```bash
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](MONITORING.md).

## Rollback Procedure

In case of critical issues, follow these rollback steps:

### Immediate Action (Within 5 minutes)

1. **Deactivate all workflows**
   ```bash
   # Stop workflow execution
   docker-compose exec -T n8n n8n stop --timeout 30
   ```

2. **Verify no ongoing operations**
   ```bash
   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**
   ```bash
   # 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)**
   ```bash
   # 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**
   ```bash
   docker-compose ps
   curl http://localhost:5678/api/v1/health
   ```

### Data Integrity Checks

```bash
# 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:**
```bash
docker-compose logs n8n
docker-compose up -d n8n --no-deps --build
```

**PostgreSQL connection fails:**
```bash
docker-compose exec postgres pg_isready
docker-compose logs postgres
```

**Milvus vector DB issues:**
```bash
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:**
```bash
docker stats
docker-compose logs -f n8n | grep "memory\|cpu"
```

**Slow database queries:**
```bash
# 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](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.