Local n8n Setup with Docker

Hello! Welcome to a new and exciting module in your n8n journey.

In the previous module, you mastered the art of integrating AI and LLMs, building sophisticated workflows that can reason, classify, and generate content. You learned to make these workflows robust and cost-effective, which are key skills for production-grade automation. Now, it's time to take the final step towards complete mastery: taking full control of the platform itself.

This module, Self-Hosting n8n with Docker, is all about running n8n on your own infrastructure. For a software developer, this is the ultimate form of ownership, giving you maximum privacy, customization, and scalability.

Today's lesson kicks off this module by tackling the foundational learning outcome: to install and run n8n locally using Docker and Docker Compose. We'll go from a bare command line to a fully functional, self-hosted n8n instance running on your machine.

Why Self-Host with Docker?

Before we begin, let's briefly touch on why we're using Docker. As a developer, you're likely familiar with containerization. Docker allows us to package n8n and its dependencies (like a database) into isolated, portable containers. This approach provides several key advantages:

• Consistency: The setup works the same way on your laptop as it would on a cloud server.
• Simplicity: Docker Compose allows us to define and manage our entire application stack (n8n, database, etc.) in a single configuration file.
• Scalability: This setup is the first step towards a production-grade, scalable architecture, which we will explore later in the course.

Step 1: Prerequisites - Docker and Docker Compose

To get started, you'll need Docker and Docker Compose installed on your system. If you already have them, that's great! You can verify your installation by running the following commands in your terminal:

docker --version
docker compose version

If you don't have them installed or need to update, the official n8n documentation provides links to the necessary installation guides.

Step 2: The Hands-On Setup

For the core of our setup, we will follow a fantastic guide from Techno Tim. His approach is well-suited for a more robust local deployment as it includes a PostgreSQL database for storing your workflow data, which is a step up from the default SQLite and a best practice for more serious use cases.

This video will be our primary guide for the next few steps. I'll break down which parts to watch and provide the code snippets for your convenience.

A. Prepare Your Project Directory

First, let's create a dedicated folder structure for our n8n project. As shown in the video (01:36 - 02:46), a common practice is to place container application stacks in the /opt/ directory on Linux/macOS, but you can create this anywhere on your machine.

In your terminal, run the following commands:

# Create a parent directory for your container stacks (if you like this convention)
# You can choose any path you prefer.
mkdir -p ~/n8n-deployment 

# Move into your new directory
cd ~/n8n-deployment

B. Create the docker-compose.yml File

This file is the blueprint for Docker. It defines the services we want to run (n8n and Postgres), how they are connected, and how they store data.

Create a file named docker-compose.yml in your ~/n8n-deployment directory and paste the following content, which is based on the configuration from Techno Tim's video (02:46 - 05:24):

version: '3.7'

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    restart: always
    ports:
      - "5678:5678"
    env_file:
      - .env
    volumes:
      - ./data:/home/node/.n8n
      - ./files:/files
    depends_on:
      - postgres

  postgres:
    image: postgres:15
    restart: always
    env_file:
      - .env
    volumes:
      - ./postgres_data:/var/lib/postgresql/data

volumes:
  data:
  postgres_data:

What this file does:

• services: Defines two services: n8n and postgres.
• image: Specifies the official Docker images to use for each service.
• ports: Maps port 5678 on your host machine to port 5678 inside the n8n container, allowing you to access n8n in your browser.
• env_file: Tells both services to load configuration variables from a file named .env.
• volumes: This is critical. It creates persistent storage. The ./data folder on your machine is mapped to /home/node/.n8n inside the container, where n8n stores all your workflows and credentials. Similarly, ./postgres_data stores the database content. This ensures your data survives container restarts.
• depends_on: Guarantees that the postgres service starts before the n8n service.

C. Create the .env File

The .env file stores configuration variables, keeping them separate from the main compose file. This is great for managing sensitive data like passwords and environment-specific settings.

Create a file named .env in the same directory and add the following, as explained in the video (05:24 - 09:27):

# Timezone for the n8n instance
GENERIC_TIMEZONE=America/New_York

# Set to 'false' for local HTTP access without a reverse proxy/SSL
N8N_SECURE_COOKIE=false

# The port n8n will run on inside the container
N8N_PORT=5678

# Set Node.js environment to production for performance
NODE_ENV=production

# PostgreSQL Database credentials
# IMPORTANT: Change these default values!
POSTGRES_DB=n8n
POSTGRES_USER=n8nuser
POSTGRES_PASSWORD=mysecretpassword

Important:

• Change GENERIC_TIMEZONE to your local timezone (e.g., Europe/Berlin).
• Crucially, change POSTGRES_PASSWORD to a secure, unique password.
• The N8N_SECURE_COOKIE=false setting is essential for accessing your local n8n instance over http://. If you were deploying this publicly with HTTPS, you would remove this line (as its default is true).

Test your understanding!

In the docker-compose.yml file, the n8n service has a volumes section: - ./data:/home/node/.n8n. What is the purpose of this line, and what would be the consequence of removing it?

Show answer

This line creates a bind mount. It maps the ./data directory on your host machine to the /home/node/.n8n directory inside the n8n container.

Purpose: The /home/node/.n8n directory is where n8n stores all its critical data, including your workflows, credentials, and execution history. By mapping it to a local folder, you ensure this data is persistent.

Consequence of removing it: Without this line, n8n would still write its data to /home/node/.n8n, but that directory would exist only within the container's temporary file system. If you were to stop and remove the container (e.g., with docker compose down), all your workflows and credentials would be permanently deleted.

Step 3: Launch and Verify

You're almost there! Now we just need to create the directories for our volumes and launch the containers.

1. Create volume directories: In your ~/n8n-deployment directory, create the folders that your docker-compose.yml expects to use for persistent data.

   mkdir data files postgres_data
   

2. Start the services: Run the Docker Compose up command. The -d flag runs the containers in "detached" mode (in the background).

   docker compose up -d
   

   Docker will now download the n8n and Postgres images (if you don't have them already) and start the containers.

3. Verify the containers are running:

   docker ps
   

   You should see two containers listed: one for n8n and one for Postgres.

4. Check the logs (optional but good practice): If you encounter any issues, checking the logs is the first step in debugging.

   # Check n8n logs
   docker logs n8n-deployment-n8n-1
   
   # Check postgres logs
   docker logs n8n-deployment-postgres-1
   

   (Note: Your container names might be slightly different. Use docker ps to get the exact names or IDs.)

Step 4: Access Your Self-Hosted n8n

Congratulations! Your n8n instance is now running locally.

Open your web browser and navigate to: http://localhost:5678

You will be greeted with a setup screen to create your owner account. Fill in your details to secure your instance and log in. You are now looking at the dashboard of your very own, self-hosted n8n!

Conclusion

In this lesson, you've successfully taken one of the biggest steps in mastering n8n: setting up a self-hosted instance. You used Docker Compose to create a robust, reproducible local environment complete with a dedicated PostgreSQL database and persistent storage for your data.

Key Takeaways:

• Docker Compose is the standard for defining and running multi-container n8n deployments.
• The docker-compose.yml file defines your services, while the .env file manages your configuration and secrets.
• Using Docker volumes (volumes:) is non-negotiable for self-hosting, as it ensures your workflows and credentials are not lost when containers are updated or restarted.
• The setup we used today—with a separate PostgreSQL database—is a scalable foundation for more advanced deployments.

Preview of the Next Lesson:

Now that you have a running instance, you might be wondering what else you can configure. In the next lesson, we will dive deeper into the .env file and explore how to configure your n8n deployment using a wide range of environment variables. This will unlock the ability to customize everything from execution settings to user management.