n8n Automated Workflow Deployment

Status: Complete
Version: v4
Purpose: Automated n8n workflow import during Docker deployment

Overview

This document describes the automated n8n workflow deployment system implemented for NudgeCampaign v4. Workflows are now automatically imported when the Docker containers start, eliminating manual import steps.

Architecture

Components

1. Workflow Files (/n8n-workflows/)

   • campaign-processor.json - Main campaign sending workflow
   • welcome-series.json - Welcome email automation

2. Import Scripts (/scripts/)

   • import-n8n-workflows.sh - Core import logic
   • docker-entrypoint.sh - Docker container entrypoint
   • import-via-api.sh - Manual import option

3. Docker Integration

   • Modified Dockerfile.dev to include scripts and workflows
   • Entrypoint script runs import automatically

How It Works

Automatic Import (Docker)

When you run docker-compose up, the following happens:

1. Container Startup

   • Docker builds the image with workflows and scripts included
   • Entrypoint script (docker-entrypoint.sh) is executed

2. Background Import Process

   • Script waits 30 seconds for n8n to fully initialize
   • Connects to n8n API using API key authentication
   • Imports each workflow JSON file
   • Creates database credentials
   • Activates workflows

3. Verification

   • Check n8n UI at http://localhost:5678
   • Login: admin / password
   • Workflows should appear in the workflow list

API Key Configuration

IMPORTANT: n8n requires an API key for programmatic access. You must:

1. First-time Setup (Manual):

   • Access n8n UI at http://localhost:5678
   • Login with admin/password
   • Navigate to Settings → API
   • Generate an API key
   • Save it to .env file as N8N_API_KEY

2. Example API Key (for reference):

   N8N_API_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIwZTVkZTM5Ni04Mzg3LTQyYWQtYmZmMi0wZDExYWE5MTNmNzEiLCJpc3MiOiJuOG4iLCJhdWQiOiJwdWJsaWMtYXBpIiwiaWF0IjoxNzU0MjMwMTQ2fQ.PcuqTYftCXV2bD9wN76Ho9vAtLP4Wv_19a8Rew_tvrY
   

3. Automated Import will then use this key for all API operations

Manual Import (Host Machine)

If automatic import fails or you need to re-import:

cd nudgecampaign-mvp-v4
./scripts/import-via-api.sh

This script:

• Connects to running n8n instance
• Imports workflows from n8n-workflows/ directory
• Sets up database credentials
• Activates all workflows

Features

Smart Import Logic

• Duplicate Prevention: Checks if workflows already exist before importing
• Retry Logic: Waits up to 150 seconds for n8n to be ready
• Error Handling: Continues even if some workflows fail
• Credential Setup: Automatically creates PostgreSQL credentials

Workflow Preparation

Before import, the script:

• Removes existing workflow IDs
• Removes version IDs
• Removes metadata
• Ensures clean import

Database Credentials

Automatically creates "NudgeCampaign DB" credential:

• Host: supabase-db (Docker) or localhost (manual)
• Port: 5432 (Docker) or 54322 (manual)
• Database: postgres
• User: postgres
• Password: postgres

Deployment Commands

Full Stack Deployment

# Start all services with automatic workflow import
docker-compose up -d

# View import logs
docker-compose logs app | grep "n8n"

# Verify workflows are imported
curl -u admin:password http://localhost:5678/api/v1/workflows

Rebuild After Workflow Changes

# Rebuild container to include new workflows
docker-compose build app

# Restart with new workflows
docker-compose up -d

Manual Workflow Management

# Import workflows manually
./scripts/import-via-api.sh

# Check n8n status
curl -u admin:password http://localhost:5678/api/v1/workflows

# Access n8n UI
open http://localhost:5678

Troubleshooting

Workflows Not Appearing

1. Check Import Logs

   docker-compose logs app | grep "workflow"
   

2. Verify n8n is Running

   docker-compose ps n8n
   

3. Manual Import

   ./scripts/import-via-api.sh
   

Import Fails

1. n8n Not Ready

   • The script waits 30 seconds by default
   • Increase wait time in docker-entrypoint.sh if needed

2. Authentication Issues

   • Verify credentials in docker-compose.yml
   • Default: admin / password

3. Network Issues

   • Ensure containers are on same network
   • Check nudge-network-v4 in docker-compose.yml

Database Connection Issues

1. Wrong Credentials

   • Check PostgreSQL is running: docker-compose ps supabase-db
   • Verify connection from n8n container

2. Manual Credential Setup

   • Open n8n UI
   • Go to Credentials
   • Add PostgreSQL credential manually

Adding New Workflows

1. Create Workflow JSON

   # Export from n8n UI or create manually
   cp your-workflow.json n8n-workflows/
   

2. Rebuild Container

   docker-compose build app
   docker-compose up -d
   

3. Or Import Manually

   ./scripts/import-via-api.sh
   

Security Notes

• Basic auth credentials are hardcoded for development
• Change credentials for production deployment
• Use environment variables for sensitive data
• Consider using n8n's built-in user management

Benefits

1. Zero Manual Steps: Workflows import automatically on deployment
2. Idempotent: Safe to run multiple times
3. Error Recovery: Continues even if some imports fail
4. Complete Setup: Includes credential configuration
5. Flexible: Works with Docker or standalone

Next Steps

For production deployment:

1. Move credentials to environment variables
2. Add workflow versioning
3. Implement backup/restore functionality
4. Add monitoring for workflow health
5. Create CI/CD pipeline for workflow updates