docs: deployment and go-live documentation
This commit is contained in:
Claude Code
400
docs/DEPLOYMENT.md
Normal file
400
docs/DEPLOYMENT.md
Normal file
@@ -0,0 +1,400 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user