n8n Local Setup

This repository provides a Docker Compose configuration for running n8n workflow automation tool locally with PostgreSQL database.

📋 Prerequisites

Before you begin, ensure you have the following installed on your system:

Required Software

Choose one of the following container runtimes:

Option 1: Docker (Recommended)

• Docker: Install Docker Desktop from docker.com
• Docker Compose: Usually included with Docker Desktop (for standalone installation, see Docker Compose docs)

Option 2: Podman (Open Source Alternative)

• Podman: Rootless, daemonless container engine
• Installation Guide: See our comprehensive Podman Installation Guide

Additional Requirements

• Git (optional): For cloning the repository

System Requirements

• RAM: Minimum 2GB available memory
• Storage: At least 1GB free disk space
• Operating System: Windows 10+, macOS 10.15+, or Linux

🚀 Quick Start

Option 1: Clone with Git

# Clone the repository
git clone https://github.com/lmaksym/n8n-local.git

# Navigate to the project directory
cd n8n-local

Option 2: Download as Archive

1. Download the repository as a ZIP file from GitHub
2. Extract the ZIP file to your desired location
3. Navigate to the extracted folder

⚙️ Configuration

Environment Setup

1. Copy the environment template:

   cp .env.example .env

2. Generate an encryption key (required for credential security):

   # On macOS/Linux:
   echo "N8N_ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env
   
   # Or manually add a 64-character hex string to .env

3. Customize settings (optional):

   • Edit .env to change the database password or timezone
   • Default timezone is Europe/Warsaw

Default Configuration

• n8n Web Interface: http://localhost:5678
• Database: PostgreSQL 15
• Access: Localhost only (not accessible from other machines on the network)
• Data Persistence: Local volumes for both n8n and PostgreSQL data

Security Features

This configuration includes several security measures for local development:

• Localhost binding: n8n is only accessible from your machine, not the network
• Encryption key: Stored credentials are encrypted (when N8N_ENCRYPTION_KEY is set)
• Pinned version: Uses a specific n8n version to prevent unexpected updates
• Health checks: Both services have health checks for reliability
• Log rotation: Prevents disk space exhaustion from logs

🏃‍♂️ Running n8n

First Time Setup

Before starting n8n for the first time, set up your environment:

# Copy environment template
cp .env.example .env

# Generate encryption key (macOS/Linux)
echo "N8N_ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env

With Docker

# Start n8n and PostgreSQL in detached mode
docker-compose up -d

With Podman

If you're using Podman instead of Docker, you have two options:

# Option 1: Using podman-compose (if available)
podman-compose up -d

# Option 2: Using docker-compose with Podman backend (recommended)
docker-compose up -d

📖 Need help installing Podman? Check our Podman Installation Guide for detailed instructions.

Verify Installation

# Check if containers are running
docker-compose ps
# or with Podman
podman-compose ps

# View logs (optional)
docker-compose logs -f n8n
# or with Podman
podman-compose logs -f n8n

Access n8n

1. Open your web browser
2. Navigate to http://localhost:5678
3. Complete the initial setup wizard
4. Start creating your workflows!

🛠️ Management Commands

Essential Commands

With Docker:

# Start services
docker-compose up -d

# Stop services
docker-compose down

# View running containers
docker-compose ps

# View logs
docker-compose logs n8n          # n8n logs only
docker-compose logs postgres     # PostgreSQL logs only
docker-compose logs -f           # Follow all logs

# Restart services
docker-compose restart

# Update to latest n8n version
docker-compose pull
docker-compose up -d

With Podman:

# Start services
podman-compose up -d
# or
docker-compose up -d  # if using Docker Compose with Podman

# Stop services
podman-compose down
# or
docker-compose down

# View running containers
podman-compose ps
# or
docker-compose ps

# View logs
podman-compose logs -f n8n
# or
docker-compose logs -f n8n

# Restart services
podman-compose restart
# or
docker-compose restart

# Update to latest n8n version
podman-compose pull
podman-compose up -d
# or
docker-compose pull
docker-compose up -d

Data Management

# Backup your n8n data (works with both Docker and Podman)
docker-compose exec postgres pg_dump -U n8n n8n > n8n_backup.sql

# Stop services (keeps data)
docker-compose down

# Remove everything including data (⚠️ DESTRUCTIVE)
docker-compose down -v

📁 Data Persistence

Your data is automatically persisted in local directories:

• ./n8n_data/ - n8n workflows, credentials, and settings
• ./postgres_data/ - PostgreSQL database files

These directories are created automatically and are excluded from Git via .gitignore.

🔧 Troubleshooting

Common Issues

Port 5678 already in use:

# Check what's using the port
lsof -i :5678  # macOS/Linux
netstat -ano | findstr :5678  # Windows

# Either stop the conflicting service or change the port in docker-compose.yml

Container won't start:

# Check container logs
docker-compose logs n8n
# or with Podman
podman-compose logs n8n

# Ensure Docker/Podman is running
docker --version
# or
podman --version

Database connection issues:

# Restart services in correct order
docker-compose down
docker-compose up -d postgres
# Wait 10 seconds
docker-compose up -d n8n

Permission issues (Linux):

# Fix ownership of data directories
sudo chown -R $USER:$USER ./n8n_data ./postgres_data

Podman-specific issues:

• See the Podman Installation Guide for Podman-specific troubleshooting

Reset Installation

To start fresh with a clean installation:

# Stop services and remove all data
docker-compose down -v
# or with Podman
podman-compose down -v

# Remove local data directories
rm -rf ./n8n_data ./postgres_data

# Start services again
docker-compose up -d
# or with Podman
podman-compose up -d

🎯 Next Steps

After successful installation:

1. Explore n8n: Check out the n8n documentation
2. Create workflows: Start with simple automation tasks
3. Configure credentials: Set up connections to your favorite services
4. Schedule workflows: Use n8n's built-in scheduler for recurring tasks

📚 Additional Resources

• n8n Official Documentation
• n8n Community Forum
• Docker Compose Documentation
• Podman Installation Guide (Alternative to Docker)
• PostgreSQL Documentation

⚠️ Security Notes

This setup is intended for local development and testing only.

What's secured:

• ✅ Port bound to localhost (not accessible from network)
• ✅ Credential encryption (when N8N_ENCRYPTION_KEY is set)
• ✅ Log rotation enabled
• ✅ Pinned n8n version

For production use, additionally:

• Use strong, unique passwords
• Enable SSL/TLS with a reverse proxy (nginx, Caddy, Traefik)
• Configure firewall rules
• Enable n8n authentication (N8N_BASIC_AUTH_ACTIVE=true)
• Set up regular backups
• Keep n8n and PostgreSQL updated

📄 License

This project is open source under the MIT License. See LICENSE file for details.

Please refer to n8n's license for usage terms.