Skip to content

N8N Auto-Setup and Workflow Import for Local Development

Date: 2025-11-04 Purpose: Automate N8N setup and workflow import for zero-configuration local development Status: ✅ Implemented

Problem Statement

When starting Slidefactory for the first time, users had to: 1. Manually complete N8N owner setup through the UI 2. Create an API key in the N8N UI 3. Add the API key to .env.local 4. Manually import any starter workflows

This created a poor first-run experience and required multiple manual steps before the system was functional.

Solution Overview

Implemented an automated initialization system that: - ✅ Automatically creates the N8N owner account on first run - ✅ Disables API key requirement for local development - ✅ Automatically imports starter workflows from JSON files - ✅ Runs only once per N8N data volume (idempotent)

Implementation Details

1. N8N Initialization Script

File: n8n-init.sh

A shell script that runs after N8N starts and: 1. Checks if already initialized (via marker file) 2. Waits for N8N to be healthy 3. Creates owner account via API 4. Imports workflows from /workflows directory 5. Marks initialization as complete

Key features: - Idempotent (won't run twice) - Uses marker file .initialized in N8N data volume - Configurable owner credentials via environment variables - Graceful error handling

2. Docker Compose Configuration

File: docker-compose.override.yml

Added n8n-init service:

n8n-init:
  image: curlimages/curl:latest
  depends_on:
    n8n:
      condition: service_healthy
  volumes:
    - n8n_data:/home/node/.n8n
    - ./n8n-init.sh:/n8n-init.sh:ro
    - ./n8n-workflows:/workflows:ro
  environment:
    - N8N_OWNER_EMAIL=admin@local.dev
    - N8N_OWNER_PASSWORD=admin
    - N8N_OWNER_FIRST_NAME=Admin
    - N8N_OWNER_LAST_NAME=User
  command: ["/bin/sh", "/n8n-init.sh"]
  network_mode: "service:n8n"

Network mode: Uses service:n8n to share N8N's network namespace, allowing localhost access.

3. Workflow Directory Structure

Directory: n8n-workflows/

Contains: - README.md - Documentation on how to add workflows - example-hello-world.json - Sample workflow - Any additional .json workflow files users want to import

4. API Authentication Changes

File: app/n8nmanager/core.py

Made API key header conditional:

# Only add API key header if configured (for local dev with disabled auth)
self.headers = {
    "Content-Type": "application/json",
    "Accept": "application/json"
}
if self.api_key:
    self.headers["X-N8N-API-KEY"] = self.api_key

File: .env.local

Set empty API key:

# API authentication is disabled for local development - no API key needed
N8N_API_KEY=""

Files Created/Modified

Created Files:

  1. n8n-init.sh - Initialization script
  2. n8n-workflows/README.md - Workflow import documentation
  3. n8n-workflows/example-hello-world.json - Sample workflow

Modified Files:

  1. docker-compose.override.yml - Added n8n-init service
  2. app/n8nmanager/core.py - Made API key optional
  3. .env.local - Set empty N8N_API_KEY

Usage

First Time Setup

# Just start docker-compose
docker-compose up

# The following happens automatically:
# 1. N8N starts and creates database
# 2. n8n-init waits for N8N to be healthy
# 3. Owner account created (admin@local.dev / admin)
# 4. Workflows imported from n8n-workflows/
# 5. Initialization complete

Accessing N8N

  • URL: http://localhost:5678
  • Basic Auth: admin / admin (for UI)
  • Owner Login: admin@local.dev / admin
  • API: No API key required

Adding Custom Workflows

Option 1: Export from UI

  1. Create workflow in N8N UI
  2. Download as JSON
  3. Save to n8n-workflows/ directory
  4. Reset volume to test import: 
    docker-compose down -v
docker-compose up

Option 2: Manual JSON

Create .json file in n8n-workflows/ with N8N workflow format.

Re-initializing N8N

To completely reset and re-import:

# Remove N8N volume
docker-compose down
docker volume rm s5-slidefactory_n8n_data

# Start fresh
docker-compose up

Configuration

Environment Variables (n8n-init service)

Variable Default Description
N8N_OWNER_EMAIL admin@local.dev Owner account email
N8N_OWNER_PASSWORD admin Owner account password
N8N_OWNER_FIRST_NAME Admin Owner first name
N8N_OWNER_LAST_NAME User Owner last name

To customize:

# docker-compose.override.yml
services:
  n8n-init:
    environment:
      - N8N_OWNER_EMAIL=your-email@example.com
      - N8N_OWNER_PASSWORD=your-secure-password

Workflow Import Details

Workflow JSON Format

Workflows must be in N8N's native JSON format:

{
  "name": "Workflow Name",
  "nodes": [...],
  "connections": {...},
  "active": false,
  "settings": {
    "executionOrder": "v1"
  },
  "versionId": "1",
  "id": "unique-workflow-id",
  "meta": {
    "instanceId": "local-dev"
  },
  "tags": []
}

Import Method

Uses N8N REST API:

POST /api/v1/workflows
Authorization: Basic YWRtaW46YWRtaW4=  # admin:admin
Content-Type: application/json

Import Logic

for workflow_file in /workflows/*.json; do
    curl -s -X POST http://localhost:5678/api/v1/workflows \
      -u "admin:admin" \
      -H "Content-Type: application/json" \
      -d @"$workflow_file"
done

Idempotency

The initialization script is idempotent:

  1. Marker file: .initialized created in /home/node/.n8n/
  2. Check on run: Script exits early if marker exists
  3. Volume persistence: Marker persists across container restarts
  4. Volume reset: Removing volume triggers re-initialization
# Check if already initialized
if [ -f "$N8N_DATA_DIR/.initialized" ]; then
    echo "N8N already initialized, skipping setup"
    exit 0
fi

Troubleshooting

Issue: n8n-init container fails

Symptom: Init container exits with error

Check: 

docker-compose logs n8n-init

Common causes: - N8N not healthy yet (increase healthcheck timeout) - Network connectivity issue - Invalid workflow JSON

Issue: Workflows not imported

Symptom: N8N starts but no workflows visible

Debug: 

# Check if workflows directory is mounted
docker-compose exec n8n-init ls /workflows

# Check initialization log
docker-compose logs n8n-init

# Verify marker file
docker-compose exec n8n ls -la /home/node/.n8n/.initialized

Issue: Owner already exists error

Symptom: Owner setup fails

Cause: N8N volume already has owner configured

Solution: This is expected and handled gracefully. The script continues with workflow import.

Issue: Re-initialization needed

Solution: 

# Remove N8N volume completely
docker-compose down
docker volume rm s5-slidefactory_n8n_data

# Restart
docker-compose up

Security Considerations

Local Development

✅ Safe for local development: - Owner password is admin (not secure for production) - Basic auth enabled for UI protection - No API key required (convenient for development) - All data in local Docker volume

Production Deployment

⚠️ DO NOT use this configuration for production: - Change owner password to strong value - Enable API key authentication - Use proper user management - Configure HTTPS - Use external database - Implement proper access controls

This configuration is designed for local development only.

Future Enhancements

Potential improvements:

  1. Workflow versioning - Track workflow changes in git
  2. Credential import - Securely import credentials for workflows
  3. Environment-specific workflows - Different workflows for dev/staging/prod
  4. Workflow validation - Check JSON validity before import
  5. Import error reporting - Better feedback on import failures
  6. Workflow dependencies - Handle workflows that depend on other workflows

Benefits

Developer Experience

✅ Zero configuration - Works out of the box ✅ Fast onboarding - New developers can start immediately ✅ Consistent setup - Everyone gets the same workflows ✅ Version controlled - Workflows tracked in git ✅ Easy reset - Simple volume removal for fresh start

Team Collaboration

✅ Shared workflows - Team members share common workflows ✅ Documentation - Workflows serve as examples ✅ Reproducibility - Identical setup across machines ✅ No manual steps - Eliminates setup errors

Testing

To test the complete setup:

# 1. Clean slate
docker-compose down -v

# 2. Start services
docker-compose up

# 3. Wait for initialization (check logs)
docker-compose logs -f n8n-init

# 4. Access N8N
open http://localhost:5678

# 5. Login with owner credentials
# Email: admin@local.dev
# Password: admin

# 6. Verify workflows imported
# Check workflows list in UI

Summary

This implementation transforms N8N from a manual setup process requiring multiple steps into a zero-configuration local development experience. Users can now:

  1. Run docker-compose up
  2. Wait for services to start
  3. Access N8N with pre-configured account
  4. Find starter workflows already imported
  5. Start building workflows immediately

No manual configuration, no API keys, no owner setup wizard - just works!