Install n8n on Raspberry Pi using Docker Compose

The Raspberry Pi, with its low power consumption and small form factor, makes an excellent platform for hosting various services at home. One such service is n8n, a powerful open-source workflow automation tool that lets you connect APIs, services, and apps with very little code. Installing n8n directly on a Raspberry Pi can sometimes be tricky due to system dependencies and specific architectures. This is where Docker Compose shines, offering a clean, isolated, and repeatable way to deploy n8n.

In this guide, I'll walk you through the process of installing n8n on your Raspberry Pi using Docker Compose, leveraging the official ARM-compatible Docker images.

Prerequisites

Before we begin, ensure you have the following:

A Raspberry Pi: Any model capable of running a modern Raspberry Pi OS (formerly Raspbian) should work, though models with 2GB RAM or more are recommended for better performance.
Raspberry Pi OS: Installed and updated.
SSH Access: Or direct access to a terminal on your Raspberry Pi.
Docker and Docker Compose: Installed on your Raspberry Pi. If not, you can install them with these commands:
```
sudo apt update
sudo apt upgrade -y
curl -sSL https://get.docker.com | sh
sudo usermod -aG docker pi # Replace 'pi' with your username if different
newgrp docker # Apply group changes immediately, or log out and back in
sudo apt install docker-compose -y
```
Note: The docker-compose package installed via apt is often the legacy docker-compose V1. If you prefer the newer docker compose (V2) plugin, you might need to install it manually. However, for most users and this guide, the V1 version works perfectly fine.

Step 1: Create a Project Directory

First, create a directory where your n8n configuration and Docker Compose file will reside. This helps keep things organized. I keep mine inside a docker directory, in the home directory.

mkdir ~/n8n
cd ~/n8n

Step 2: Create the Docker Compose File

Now, we'll create the docker-compose.yml file that defines how n8n and its dependencies will run. You'll need a text editor like nano or vim for this. We'll use nano in this example.

nano docker-compose.yml

Paste the following content into the file:

version: "3.8" # Use 3.7 if you are using the old docker-compose command

services:
  n8n:
    image: n8nio/n8n # Uses the official n8n image which supports ARM architecture
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678" # Host:Container port mapping
    volumes:
      - ~/.n8n:/home/node/.n8n # Persist n8n data
    environment:
      - N8N_HOST=${N8N_HOST:-localhost}
      - N8N_PORT=5678
      - N8N_PROTOCOL=${N8N_PROTOCOL:-http}
      - WEBHOOK_URL=${WEBHOOK_URL:-http://localhost:5678/} # Adjust if using a domain or IP
      - N8N_BASIC_AUTH_ACTIVE=true # Enable basic authentication
      - N8N_BASIC_AUTH_USER=${N8N_BASIC_AUTH_USER:-user} # Default username
      - N8N_BASIC_AUTH_PASSWORD=${N8N_BASIC_AUTH_PASSWORD:-password} # Default password
      - TZ=Eurome/Rome # Set your timezone, e.g., Europe/Berlin

Explanation of the file:

image: n8nio/n8n: Specifies the official n8n Docker image. This image is multi-arch, meaning it will automatically pull the correct ARM version for your Raspberry Pi.
container_name: n8n: Gives a friendly name to your n8n container.
restart: unless-stopped: Ensures n8n automatically restarts if it crashes or if your Raspberry Pi reboots.
ports: - "5678:5678": Maps port 5678 on your Raspberry Pi to port 5678 inside the Docker container. This is how you'll access n8n from your browser.
volumes: - ~/.n8n:/home/node/.n8n: This is crucial! It maps a local directory on your Raspberry Pi (~/.n8n) to the n8n data directory inside the container. This ensures all your workflows, credentials, and settings are persistent even if you update or recreate the container.
environment: Sets various environment variables for n8n:
- N8N_HOST, N8N_PORT, N8N_PROTOCOL, WEBHOOK_URL: Configure how n8n identifies itself. If you're accessing it via your Pi's IP address, you might change WEBHOOK_URL to http://<YOUR_PI_IP_ADDRESS>:5678/. If you're setting up a domain and reverse proxy later, you'll need to update these.
- N8N_BASIC_AUTH_ACTIVE, N8N_BASIC_AUTH_USER, N8N_BASIC_AUTH_PASSWORD: These enable basic authentication for your n8n instance. It's highly recommended to change user and password to strong, unique credentials.
- TZ: Set your correct timezone.

After pasting the content, save and exit nano (Ctrl + X, then Y, then Enter).

Step 3: Start n8n with Docker Compose

With your docker-compose.yml file ready, navigate to the directory where you saved it (if you're not already there) and run the following command:

docker-compose up -d

up: Starts the services defined in docker-compose.yml.
-d: Runs the services in detached mode (in the background).

Docker Compose will now pull the n8n image (if not already present), create the container, and start n8n. This might take a few minutes on the first run, especially if the image needs to be downloaded.

You can check the status of your running container with:

docker-compose ps

You should see n8n listed with a status of Up.

To view the logs of your n8n container (useful for troubleshooting):

docker-compose logs -f n8n

Press Ctrl + C to exit the logs.

Step 4: Access n8n

Once the container is running, open your web browser and navigate to:

http://<YOUR_RASPBERRY_PI_IP_ADDRESS>:5678

Replace <YOUR_RASPBERRY_PI_IP_ADDRESS> with the actual IP address of your Raspberry Pi. You can find your Pi's IP address by running hostname -I on its terminal.

You should be prompted for the basic authentication credentials you set in the docker-compose.yml file (user and password by default, or your changed credentials). After entering them, you will see the n8n interface, ready for you to create your first workflow!

Managing your n8n instance

Here are some useful Docker Compose commands for managing your n8n instance:

To stop n8n:
```
docker-compose stop
```
To stop and remove the n8n container (keeping data):
```
docker-compose down
```
Note: This will remove the container but keep the data volume (~/.n8n), so your workflows are safe.
To restart n8n (e.g., after making changes to the docker-compose.yml):
```
docker-compose restart n8n
```
To update n8n to the latest version:
```
docker-compose pull n8n
docker-compose up -d
```
This will pull the newest image and recreate the container, preserving your data.

Conclusion

You've successfully installed n8n on your Raspberry Pi using Docker Compose! This setup provides a robust, maintainable, and isolated environment for your workflow automation needs. With n8n running on your low-power Pi, you have a powerful tool at your fingertips to automate tasks, connect services, and streamline processes right from your home server. Enjoy building your automations!

This post contains affiliate links. As an Amazon Associate, I earn from qualifying purchases you make. This means I may earn a small commission if you purchase through my links at no extra cost to you.