Tech vortex

How to Install n8n on a Raspberry Pi: Step-by-Step Guide

Introduction

In today’s fast-paced world, automation is a game-changer. It helps us save time, reduce errors, and streamline repetitive tasks. Whether it’s sending emails, updating spreadsheets, or controlling smart home devices, automation frees you to focus on what matters most.

One of the most exciting tools for automation enthusiasts is n8n (pronounced “n-eight-n”). n8n is an open-source workflow automation platform. Think of it like a “glue” that connects different apps and services — like Gmail, Slack, Twitter, or home automation devices — so they can work together automatically without you having to write a lot of code.

You can run n8n on many devices, but one of the best options is the Raspberry Pi. This tiny, affordable computer is famous for its low power consumption and flexibility. Running n8n on a Raspberry Pi lets you have a personal automation server running 24/7, right at home, with minimal energy use and cost.

This guide will take you through everything you need to know to get n8n up and running on a Raspberry Pi — from preparing your system and installing Docker, to launching n8n, accessing it, and even setting it up securely for remote use. By the end, you’ll have a powerful automation hub at your fingertips.

Prerequisites

Before jumping into installation, let’s make sure you have all the hardware, software, and knowledge you’ll need.

Hardware Requirements

  • Raspberry Pi Model: While n8n can run on various Raspberry Pi models, we recommend the Raspberry Pi 4 with at least 2GB of RAM. The Pi 4 offers a significant speed boost over earlier versions, which is helpful when running applications like n8n that handle multiple tasks or complex workflows. If you only have a Pi 3, it can work, but expect slower performance.
  • Storage: A microSD card of at least 16GB is recommended for your Raspberry Pi OS and the n8n installation. Faster SD cards (Class 10 or UHS-1) improve system responsiveness.
  • Power Supply: Use a reliable power supply designed for the Raspberry Pi to avoid unexpected shutdowns.

Software Requirements

  • Raspberry Pi OS: This is the official operating system for the Raspberry Pi. You can use either the Lite version, which is command-line only and uses fewer resources, or the Desktop version that includes a graphical interface. Both work well for running n8n.
  • Internet Connection: Your Raspberry Pi needs to be connected to the internet for downloading software and container images.
  • Basic Command Line Skills: Installing and configuring software on the Raspberry Pi will require using the terminal. Don’t worry if you’re new — the commands are straightforward and we’ll explain each step carefully.

Software You Will Install

  • Docker & Docker Compose: Docker allows you to run applications in lightweight containers. This makes installing n8n easy, as all its dependencies come packaged in the container. Docker Compose is a tool that helps you define and manage multi-container Docker applications via simple YAML files.
  • Node.js: This is only required if you choose to install n8n without Docker. For most users, the Docker approach is easier and more reliable, so we won’t cover the Node.js method in detail here.

System Preparation

Before installing any new software, it’s important to update your Raspberry Pi OS to make sure everything is up-to-date and secure.

Open the terminal on your Raspberry Pi (or SSH into it from another computer) and run:

Bash
sudo apt update && sudo apt upgrade -y
  • sudo apt update fetches the latest package lists from the repositories.
  • sudo apt upgrade -y upgrades all installed packages to their latest versions automatically.

Once that’s done, install some useful utilities:

Bash
sudo apt install curl git -y
  • curl is a tool to download files and data from URLs — you’ll use it to install Docker.
  • git allows you to clone code repositories, handy if you want to pull configuration files or example workflows later.

Install Docker and Docker Compose

Docker is the backbone of our installation because it bundles n8n with everything it needs to run.

Installing Docker

Run the official installation script with:

Bash
curl -sSL https://get.docker.com | sh

This script detects your system and installs Docker automatically.

Once installed, add your user to the docker group so you can run Docker commands without needing sudo:

Bash
sudo usermod -aG docker $USER

Important: You need to log out and log back in for this group change to take effect. If you are SSH’d into the Pi, close and reconnect your session.

Verify Docker works by running:

Bash
docker run hello-world

You should see a welcome message from Docker confirming the installation.

Installing Docker Compose

Docker Compose is included in many modern Raspberry Pi OS versions, but you can install it explicitly with:

Bash
sudo apt install docker-compose -y

Check the installed version:

Bash
docker-compose --version

You should see something like docker-compose version 1.29.2, build 5becea4c.

Set Up n8n with Docker Compose

Now it’s time to configure n8n.

Step 1: Create a Directory for n8n

It’s good practice to keep your n8n files organized. Run:

Bash
mkdir ~/n8n && cd ~/n8n

This creates a folder named n8n in your home directory and moves you inside it.

Step 2: Create the Docker Compose File

Create a new file called docker-compose.yml with your favorite text editor. For example:

Bash
nano docker-compose.yml

Paste the following content:

YAML
version: "3"

services:
  n8n:
    image: n8nio/n8n
    restart: always
    ports:
      - "5678:5678"
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=yourpassword
      - TZ=Europe/London
    volumes:
      - ./n8n_data:/home/node/.n8n

What Does This Mean?

  • version: "3": Defines the Docker Compose file format version.
  • Under services, we define our container named n8n.
  • image: n8nio/n8n: Tells Docker to use the official n8n image.
  • restart: always: Automatically restarts the container if it crashes or if the Raspberry Pi reboots.
  • ports: "5678:5678": Maps port 5678 inside the container to port 5678 on your Raspberry Pi. This allows you to access n8n via http://<your_pi_ip>
    :5678    .
  • environment: Defines environment variables to configure n8n:
    • N8N_BASIC_AUTH_
      ACTIVE=true      : Enables login protection.
    • N8N_BASIC_AUTH_
      USER=admin      : Sets the username (change as you like).
    • N8N_BASIC_AUTH_
      PASSWORD=
      yourpassword      : Replace yourpassword with a strong password.
    • TZ=Europe/London: Sets your timezone for correct timestamps. Replace with your own, e.g., America/New_York.
  • volumes: Persists your workflow data and settings on your Raspberry Pi, so they don’t get lost if the container restarts or updates.

Save and close the file (Ctrl + X, then Y, then Enter if using nano).

Step 3: Start the n8n Container

Run:

Bash
docker-compose up -d

This command will:

  • Download the n8n Docker image (if not already downloaded).
  • Start the container in detached mode (running in the background).

To check if it’s running, use:

Bash
docker ps

You should see the n8n container running and listening on port 5678.

Accessing n8n

You’re now ready to use n8n!

Open your web browser on any device connected to the same network as your Raspberry Pi and enter:

Plaintext
http://<your_pi_ip>:5678

Replace <your_pi_ip> with your Raspberry Pi’s local IP address. You can find it by running:

Bash
hostname -I

or checking your router’s connected devices list.

Logging In

You will see a login screen asking for a username and password.

Use:

  • Username: admin (or what you set in the Docker Compose file)
  • Password: Your chosen password

After logging in, you’ll land on the n8n dashboard, where you can start creating and managing workflows.

Optional – Run n8n as a Subdomain with Reverse Proxy

Running n8n on your local network is great, but what if you want to access it securely from anywhere?

The answer is to use a reverse proxy with Nginx and secure it with Let’s Encrypt SSL certificates.

What is a Reverse Proxy?

A reverse proxy acts like a middleman between the internet and your n8n service. It forwards requests from your domain name (like n8n.yourdomain.com) to your Raspberry Pi and handles SSL encryption.

Why Use HTTPS?

By default, your connection to n8n is unencrypted. HTTPS encrypts the data exchanged, protecting your login credentials and workflows from prying eyes.

Basic Steps to Set This Up

  1. Install Nginx:

Bash
sudo apt install nginx -y

  1. Configure Your Domain:

    Register a domain or subdomain and point its DNS A record to your home’s public IP address. If you have a dynamic IP, consider using a dynamic DNS service like DuckDNS or No-IP.

  2. Create an Nginx Configuration File:

    Example config for your subdomain:
Nginx
server {
    listen 80;
    server_name n8n.yourdomain.com;

    location / {
        proxy_pass http://localhost:5678;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

  1. Get SSL Certificates Using Certbot:

Install Certbot:

Bash
sudo apt install certbot python3-certbot-nginx -y

Run Certbot:

Bash
sudo certbot --nginx -d n8n.yourdomain.com

Follow the prompts to obtain and install certificates.

  1. Test Your Setup:

    Visit https://n8n.yourdomain
    .com     and you should see the secure n8n login page.

Notes

  • Opening your home network to the internet involves security risks. Make sure your Raspberry Pi is fully updated and secure.
  • Using basic auth (set in Docker Compose) adds an extra layer of protection.
  • For more detailed instructions, look for guides on “Nginx reverse proxy with Let’s Encrypt on Raspberry Pi”.

Auto-start and Persistence

Automatic Start on Boot

Because of the restart: always option in Docker Compose, your n8n container will start automatically whenever your Raspberry Pi boots up. This means your automation server is always available, even after power outages or reboots.

If you want to manually start, stop, or restart n8n, use these commands inside your ~/n8n folder:

Bash
docker-compose stop    # Stop n8n
docker-compose start   # Start n8n
docker-compose restart # Restart n8n

Data Persistence

All your workflows, credentials, and configurations are saved in the n8n_data folder on your Raspberry Pi (as mounted in Docker Compose).

This means you won’t lose your data if you update the container or reboot the device.

Backup Recommendations

Consider regularly backing up the n8n_data folder to another device or cloud storage. You can use simple tools like rsync or create scripts to automate backups.

Conclusion

You’ve successfully installed and configured n8n on your Raspberry Pi, turning it into a powerful, energy-efficient automation server that runs 24/7.

By using Docker and Docker Compose, you simplified the installation and management of n8n, ensuring it will restart automatically and keep your workflows safe.

Benefits Recap:

  • Cost-Effective: Raspberry Pi’s low energy use saves money over time.
  • Always On: Keeps your automations running continuously without needing a PC.
  • Secure: Basic auth and optional HTTPS setup protect your workflows.
  • Open Source: No vendor lock-in or subscription fees.
  • Highly Customizable: Connect to hundreds of apps and services with ease.

What to Do Next?

  • Explore n8n Workflows: Experiment with pre-built templates or build your own workflows to automate emails, notifications, data processing, or smart home tasks.
  • Integrate APIs: Connect services like Google Sheets, Twitter, Slack, or custom APIs.
  • Expand Your Setup: Add more containers or integrate with other home automation tools like Home Assistant.
  • Learn Advanced Features: Use n8n’s built-in functions, expressions, and scripting capabilities to create complex automations.

With your Raspberry Pi and n8n working together, you’ve taken a big step towards a smarter, automated lifestyle — all controlled from your own device.