How to Selfhost n8n in Cloud/Locally with Docker

Below is a comprehensive tutorial that guides you through the process of self-hosting n8n using either npm or Docker. This tutorial covers the fundamental concepts, configurations, and best practices to get your own automation workflows up and running. By the end of this guide, you will have a clear understanding of how to install, configure, and maintain n8n locally or on a server of your choice. Enjoy! 1. Introduction: What Is n8n? n8n is an open-source workflow automation tool that enables you to connect various services, APIs, and data across different platforms in a seamless manner. It stands out from many other automation platforms for several reasons: It's open-source, meaning you have full access to the source code and can customize it to your liking or inspect it for security issues. It provides a user-friendly interface for designing workflows, making it easy for both developers and non-developers to build complex automations. You can self-host n8n, giving you control over your data and the platform instead of relying on a third-party service. It supports a large library of integrations (also known as “nodes”), and you can easily create your own to connect with virtually any service or API. In practice, n8n can help you automate tasks, such as sending Slack notifications when a new row is added to a Google Sheet, triggering data transformations from an API response, or orchestrating an entire pipeline of microservices. Because it’s so flexible, you can tailor your workflows precisely to your organization’s needs or personal projects. This tutorial focuses on the process of installing and hosting n8n in your own infrastructure. Whether you prefer a Node.js-based installation (with npm) or a container-based setup (with Docker), you will find the detailed steps here. By self-hosting n8n, you can keep your data under your control, fine-tune performance, and scale the platform as your business needs evolve. 2. Prerequisites and Requirements Before diving into the setup steps, it’s crucial to ensure that you have the right prerequisites in place. This section covers the hardware, software, and environment you will need to successfully install and run n8n, including: A host machine or server: You can use your local machine for experimentation, although if you’re setting up for production, you might want a virtual private server (VPS) or dedicated server. n8n is relatively lightweight but benefits from a stable system with sufficient RAM (e.g., 2 GB or more), CPU resources, and storage. An operating system: Linux is the most common choice (Ubuntu, Debian, CentOS, etc.), but n8n can also run on MacOS, Windows, or other Unix-like systems. Docker installations can be managed on any OS that supports Docker (Linux, Windows, macOS). Network considerations: If you want to make your n8n installation accessible from the internet, ensure your network is set up properly with relevant firewall rules and open ports. Typically, n8n defaults to port 5678, so if you plan external access, you may map or open that port. Node.js (if installing via npm): You need Node.js (LTS version recommended, e.g., 16.x or 18.x) installed. npm (Node Package Manager) or Yarn to handle package installations. Docker (if installing via Docker): Docker should be installed on your machine or server. A Docker daemon running, with enough privileges to pull images from Docker Hub. Basic command-line knowledge: Comfort navigating directories and editing configuration files will be beneficial. Ability to manage environment variables and run commands in the terminal. In the upcoming sections, we will explore both npm-based and Docker-based installations. Before that, it’s important to mention that either approach is valid—your choice depends on your familiarity with Node.js vs. containerization, your existing infrastructure, and your preference for keeping processes and dependencies isolated. 3. Preparing Your Environment Regardless of your installation method, it’s advisable to structure your environment in a way that is easy to manage. Below are best practices to follow: Create a dedicated user or directory for n8n: If you are on a shared server, consider creating a dedicated user to run the n8n process. This approach helps in isolating the process and enforcing file permissions more effectively. In local or container-based environments, ensure that the folder structure for n8n workflows and data is well-defined and easy to back up. Setup environment variables: n8n offers a wide range of environment variables that allow you to tweak performance, set up credentials, or configure webhooks. For example, you can set the environment variable N8N_PORT to change the default port, or N8N_HOST if you need n8n to listen on a specific hostname. Make a plan for data storage: In many workflows, n8n may store data locally, such as logs or node credentials (en

Apr 4, 2025 - 10:04

How to Selfhost n8n in Cloud/Locally with Docker

Below is a comprehensive tutorial that guides you through the process of self-hosting n8n using either npm or Docker. This tutorial covers the fundamental concepts, configurations, and best practices to get your own automation workflows up and running. By the end of this guide, you will have a clear understanding of how to install, configure, and maintain n8n locally or on a server of your choice. Enjoy!

1. Introduction: What Is n8n?

n8n is an open-source workflow automation tool that enables you to connect various services, APIs, and data across different platforms in a seamless manner. It stands out from many other automation platforms for several reasons:

It's open-source, meaning you have full access to the source code and can customize it to your liking or inspect it for security issues.
It provides a user-friendly interface for designing workflows, making it easy for both developers and non-developers to build complex automations.
You can self-host n8n, giving you control over your data and the platform instead of relying on a third-party service.
It supports a large library of integrations (also known as “nodes”), and you can easily create your own to connect with virtually any service or API.

In practice, n8n can help you automate tasks, such as sending Slack notifications when a new row is added to a Google Sheet, triggering data transformations from an API response, or orchestrating an entire pipeline of microservices. Because it’s so flexible, you can tailor your workflows precisely to your organization’s needs or personal projects.

This tutorial focuses on the process of installing and hosting n8n in your own infrastructure. Whether you prefer a Node.js-based installation (with npm) or a container-based setup (with Docker), you will find the detailed steps here. By self-hosting n8n, you can keep your data under your control, fine-tune performance, and scale the platform as your business needs evolve.

2. Prerequisites and Requirements

Before diving into the setup steps, it’s crucial to ensure that you have the right prerequisites in place. This section covers the hardware, software, and environment you will need to successfully install and run n8n, including:

A host machine or server:
- You can use your local machine for experimentation, although if you’re setting up for production, you might want a virtual private server (VPS) or dedicated server.
- n8n is relatively lightweight but benefits from a stable system with sufficient RAM (e.g., 2 GB or more), CPU resources, and storage.
An operating system:
- Linux is the most common choice (Ubuntu, Debian, CentOS, etc.), but n8n can also run on MacOS, Windows, or other Unix-like systems.
- Docker installations can be managed on any OS that supports Docker (Linux, Windows, macOS).
Network considerations:
- If you want to make your n8n installation accessible from the internet, ensure your network is set up properly with relevant firewall rules and open ports.
- Typically, n8n defaults to port 5678, so if you plan external access, you may map or open that port.
Node.js (if installing via npm):
- You need Node.js (LTS version recommended, e.g., 16.x or 18.x) installed.
- npm (Node Package Manager) or Yarn to handle package installations.
Docker (if installing via Docker):
- Docker should be installed on your machine or server.
- A Docker daemon running, with enough privileges to pull images from Docker Hub.
Basic command-line knowledge:
- Comfort navigating directories and editing configuration files will be beneficial.
- Ability to manage environment variables and run commands in the terminal.

In the upcoming sections, we will explore both npm-based and Docker-based installations. Before that, it’s important to mention that either approach is valid—your choice depends on your familiarity with Node.js vs. containerization, your existing infrastructure, and your preference for keeping processes and dependencies isolated.

3. Preparing Your Environment

Regardless of your installation method, it’s advisable to structure your environment in a way that is easy to manage. Below are best practices to follow:

Create a dedicated user or directory for n8n:
- If you are on a shared server, consider creating a dedicated user to run the n8n process. This approach helps in isolating the process and enforcing file permissions more effectively.
- In local or container-based environments, ensure that the folder structure for n8n workflows and data is well-defined and easy to back up.
Setup environment variables:
- n8n offers a wide range of environment variables that allow you to tweak performance, set up credentials, or configure webhooks.
- For example, you can set the environment variable N8N_PORT to change the default port, or N8N_HOST if you need n8n to listen on a specific hostname.
Make a plan for data storage:
- In many workflows, n8n may store data locally, such as logs or node credentials (encrypted).
- If you want to persist data beyond the service’s lifetime (for Docker-based installs), bind mount or use volumes so that data remains accessible and saved when you remove or recreate containers.
Security best practices:
- Make sure your server has security patches installed.
- If you plan an internet-facing deployment, configure SSL/TLS with a certificate.
- Enable authentication in n8n so that unauthorized users cannot access your workflows.

Next, we will dive into self-hosting n8n in two distinct methods: npm and Docker. Choose the one that best fits your use case.

4. Self-hosting n8n Using npm

4.1 Installing Node.js and npm

If you don’t already have Node.js installed, follow these general steps:

Visit the official Node.js website (https://nodejs.org/) and install the latest LTS version for your operating system.
After installation, open your terminal or command prompt and verify that Node.js and npm are installed correctly:

node -v
npm -v

Optionally, if you prefer a version manager like nvm (Node Version Manager), you can install Node.js via nvm to manage multiple Node.js environments more cleanly.

4.2 Installing n8n Globally

Once Node.js and npm are installed, installing n8n is straightforward:

npm install n8n -g

The -g flag installs n8n globally on your system, allowing you to run the n8n command from any directory. If you’re using a dedicated server, you might consider installing n8n locally within a project folder, but for simplicity, many users do a global installation.

4.3 Basic Configuration with npm

n8n can be configured via environment variables or command-line parameters. Some commonly used environment variables include:

N8N_PORT: change the default port (default is 5678).
N8N_HOST: specify the host IP or name to bind to (default is localhost), relevant if you want external access.
N8N_BASIC_AUTH_ACTIVE, N8N_BASIC_AUTH_USER, N8N_BASIC_AUTH_PASSWORD: enable basic authentication for the n8n UI.

To keep your environment variables organized, create an .env file in a designated folder (for example, /home/user/n8n/):

N8N_PORT=5678
N8N_HOST="0.0.0.0"
N8N_BASIC_AUTH_ACTIVE=true
N8N_BASIC_AUTH_USER="admin"
N8N_BASIC_AUTH_PASSWORD="securepassword"

Then, export these variables before starting n8n:

export $(cat /home/user/n8n/.env | xargs)

Alternatively, you can place them in your shell configuration (e.g., ~/.bashrc or ~/.zshrc) so that they’re automatically set on login.

4.4 Running n8n with npm

Once your environment is configured, start n8n in the terminal:

n8n

If everything is set correctly, you’ll see console logs indicating that n8n has started on the specified port. Example output may include lines such as:

Initializing n8n process...
n8n ready on 0.0.0.0, port 5678
Version: 0.xxx.x

Point your browser to http://:5678 (replacing with your actual IP or hostname). If you enabled basic auth, provide the username and password you configured. You will be greeted by the n8n user interface where you can begin creating workflows.

4.5 Managing Your n8n Process

If you run n8n in a standard terminal session, it will stop when you close your terminal or if your system reboots. For production environments, you want n8n to start automatically on boot and gracefully handle restarts. Two popular approaches include:

Using a process manager like PM2:
- Install PM2 globally:
```
 npm install pm2 -g
```

Start n8n with PM2:
```
 pm2 start n8n --name n8n
```
You can then configure PM2 to start on boot:
```
 pm2 startup
 pm2 save
```

Using systemd (on Linux):

Create a systemd unit file (e.g., /etc/systemd/system/n8n.service):

 [Unit]
 Description=n8n - Workflow Automation
 After=network.target

 [Service]
 Type=simple
 ExecStart=/usr/bin/env n8n
 Restart=always
 User=n8n
 EnvironmentFile=/home/n8n/.env

 [Install]
 WantedBy=multi-user.target

Adjust paths as necessary. Then enable and start the service:

 systemctl daemon-reload
 systemctl enable n8n
 systemctl start n8n

With a process manager in place, you’ll have more reliability. Logs can be inspected, restarts can be automated, and you can ensure your system remains in your desired state even after reboots.

5. Self-hosting n8n Using Docker

If you prefer containerization or your infrastructure revolves around Docker and orchestration tools (like Docker Compose, Kubernetes, etc.), Docker can be an excellent choice for self-hosting. It simplifies the environment setup by packaging n8n and all its dependencies into an isolated container.

5.1 Installing Docker

First, ensure Docker is installed on your machine or server. Steps vary depending on your OS:

Linux (Ubuntu example):

   sudo apt-get update
   sudo apt-get install \
     ca-certificates \
     curl \
     gnupg \
     lsb-release

   curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
   echo \
     "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
     $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

   sudo apt-get update
   sudo apt-get install docker-ce docker-ce-cli containerd.io

Windows / macOS:
- Download the Docker Desktop installer from https://www.docker.com/, and follow the guided installation.
- Verify Docker is running and that you can open a terminal (or Docker Cli) to run commands.

Once completed, verify Docker installation:

docker --version

5.2 Pulling the n8n Docker Image

n8n provides an official Docker image. To get it, simply run:

docker pull n8nio/n8n

This pulls the latest stable image. If you want a specific version, you can include a tag, such as docker pull n8nio/n8n:0.210.0.

5.3 Configuring n8n in Docker

Similar to the npm installation, you can control n8n configurations using environment variables. If you want to enable basic authentication, run it on a specific port, or configure a custom domain, you do so by passing environment variables to the Docker container. You also have the option to use a .env file in conjunction with Docker Compose.

A basic environment file for Docker might look like this (.env in your project folder):

# .env
N8N_PORT=5678
N8N_HOST="0.0.0.0"
N8N_BASIC_AUTH_ACTIVE=true
N8N_BASIC_AUTH_USER="admin"
N8N_BASIC_AUTH_PASSWORD="securepassword"

5.4 Running n8n with Docker

You have two primary ways to launch n8n with Docker: a basic docker run command or a docker-compose.yml file. Below are examples of both.

5.4.1 Using docker run

You can run n8n directly:

docker run -it --rm \
  -p 5678:5678 \
  -e N8N_BASIC_AUTH_ACTIVE=true \
  -e N8N_BASIC_AUTH_USER=admin \
  -e N8N_BASIC_AUTH_PASSWORD=securepassword \
  n8nio/n8n

In this example, we:

Map port 5678 inside the container to port 5678 on the host (-p 5678:5678).
Pass environment variables (-e N8N_BASIC_AUTH_ACTIVE=true) to configure basic auth.
Use the official n8nio/n8n image from Docker Hub.

Once the container is running, you can visit http://:5678 in your browser. Stopping the container is as simple as typing Ctrl + C or sending a stop signal in the terminal.

5.4.2 Using Docker Compose

Docker Compose makes it easier to manage complex configurations. Create a docker-compose.yml in a dedicated folder (e.g., /home/user/n8n-docker/):

version: '3.8'

services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    restart: always
    ports:
      - "5678:5678"
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=securepassword
      - N8N_HOST=0.0.0.0
    volumes:
      - ./data:/home/node/.n8n

Key points:

image: n8nio/n8n:latest ensures we grab the latest version of n8n.
restart: always ensures the container automatically restarts if it crashes or if the server reboots.
ports instructs Docker to map the container’s port 5678 to your host’s 5678.
environment sets environment variables.
volumes ensures persistent data storage so that your workflows and credentials aren’t lost when the container recreates.

Next, run:

docker-compose up -d

The -d flag runs the container in the background (detached). Check logs:

docker-compose logs -f

You should see the container’s initialization messages. When you navigate to http://:5678, you’ll see the n8n interface. Use the credentials configured in your environment variables if you enabled basic authentication.

5.5 Managing and Updating Your Docker Container

Managing containers is straightforward with Docker Compose or the Docker CLI:

To stop the container:

  docker-compose down

To update n8n to the latest version:

  docker-compose pull
  docker-compose up -d

To check the container’s logs in real-time:

  docker-compose logs -f

If using purely Docker CLI (without Docker Compose), you can do similar steps with docker stop, docker rm, docker pull, and docker run. Docker Compose just streamlines the process and centralizes your configurations in docker-compose.yml.

6. Common Configurations and Tips

Once you have n8n up and running, you’ll likely want to tailor it further to your requirements. Here are some popular configurations and tips:

SSL/TLS Setup:
- For production, you’ll want to serve n8n over HTTPS. Consider using a reverse proxy (e.g., Nginx, Traefik) that handles SSL termination and proxies requests to n8n.
- Tools like Let’s Encrypt can provide free SSL certificates. An example Docker setup involves running n8n behind a secure reverse proxy using something like nginx-proxy or Traefik.
Customizing Data Directory:
- If you want your n8n data stored in a specific folder, pass environment variables such as -e N8N_USER_FOLDER=/my-n8n-data.
- Or in docker-compose.yml volumes:
```
 volumes:
   - /var/lib/n8n:/home/node/.n8n
```
Database Configuration:
- By default, n8n uses SQLite, which is sufficient for smaller-scale use. However, if you anticipate heavier load or concurrency, you can configure n8n to use MySQL or PostgreSQL by setting environment variables like DB_TYPE=postgresdb, DB_POSTGRESDB_HOST=..., etc.
- With Docker Compose, you can add a PostgreSQL or MySQL service to your stack.
Scaling Out:
- n8n has some constraints around concurrency; each container or process typically runs one main instance. For high availability or load distribution, you may explore n8n’s documentation on scaling with queue mode and additional worker processes.
- In multi-container setups, consider an external database that all containers can connect to, ensuring consistent state and allowing for parallel processing.
IP Whitelisting:
- If your workflows or triggers allow incoming traffic, configure firewall rules or reverse proxies to only allow known IP ranges. This approach reduces the chance of unauthorized access.
Workflow Management:
- The user interface allows you to manage and design workflows. If you’re building large-scale automations, keep them modular, test small pieces at a time, and leverage sub-workflows or separate flows for better maintainability.

7. Security Considerations

Self-hosting n8n grants you complete control but also requires that you take responsibility for security. Some best practices include:

Enable authentication:
- The simplest approach is enabling basic authentication via environment variables. For more advanced setups, a reverse proxy with OAuth or other single sign-on (SSO) methods may be employed.
Use SSL/TLS:
- Never expose your n8n instance publicly over plain HTTP without encryption, especially if it contains sensitive workflows or credentials. Use a reverse proxy or built-in methods to secure communications.
Restrict access:
- For internal automation, consider binding n8n to a private network interface or restricting access to an internal VPN or local IP range.
- Lock down inbound traffic at the server’s firewall level.
Keep software up to date:
- Update n8n regularly to get the latest features, security patches, and compatibility enhancements.
- Also keep your operating system and dependencies patched.
Use strong credentials:
- When using basic auth, ensure you pick a strong, long password.
- For environment variables, store them securely rather than inside version control.
Log and monitor:
- Regularly inspect logs for unusual activity.
- If you notice suspicious behavior, investigate and apply additional controls (e.g., IP blocks, forced password rotation).

By adhering to these practices, you’ll reduce the risk of unauthorized access or data leakage.

8. Troubleshooting

Even with a straightforward setup, you may encounter common issues. Here are quick troubleshooting tips:

Port Conflicts:
- If n8n fails to start and you see an error about port 5678 in use, check if another service is running on that port. Either kill that service or change the port with N8N_PORT=anotherPort.
Permissions Errors (npm-based install):
- If installing globally on Linux, use sudo npm install n8n -g with caution or consider a node version manager which bypasses root installs.
- Verify that the user running n8n has write access to the folder storing data, logs, or credentials.
Database Connection Issues:
- When using an external DB like PostgreSQL or MySQL, ensure environment variables are correct (DB_TYPE, DB_POSTGRESDB_HOST, DB_POSTGRESDB_PORT, etc.).
- Check firewall rules that might block connections between your n8n container and the DB host.
Docker Container Crashing:
- If the container restarts repeatedly, inspect logs with docker-compose logs -f or docker logs to see the cause.
- Common reasons: improper environment variable setup, missing volumes, database misconfiguration.
Repeated Credential Prompts:
- If you keep being asked to log in after enabling basic auth, verify that your environment variables match the correct user/password. Also ensure your reverse proxy (if used) is correctly forwarding headers and not rewriting or blocking cookies.
Workflow Trigger Not Firing:
- For webhooks, confirm that external services can reach your n8n endpoint. Check firewall settings or domain resolution.
- For cron triggers, confirm that your n8n instance is actively running. If the container or process is stopped, the cron triggers won’t execute.

If issues persist, refer to the official n8n documentation or community forums for more support. Since n8n is open-source, the community is vibrant and welcoming to new contributors and users.

9. Conclusion

Self-hosting n8n offers tremendous flexibility and control. You now have a thorough understanding of two main installation methods—npm and Docker. Here’s a quick recap:

The npm approach is suitable for those who want direct Node.js control, or if you’re already working in a Node-friendly environment. It requires installing Node.js, setting environment variables, and using either a process manager or systemd for reliability.
The Docker approach is excellent if you prefer container-based workloads or want an isolated environment with minimal setup. Using either docker run or Docker Compose, you can spin up n8n quickly while benefiting from containerized best practices.

No matter the method you choose, be sure to implement security steps (authentication, SSL, firewalls) and plan out your data storage for a robust, maintainable self-hosted environment. Keep your n8n installation up to date, monitor logs, and refine workflows as your organization’s needs evolve.

We’ve touched on topics like environment configurations, persistent volumes, reverse proxies, and advanced database options. These should set you on a strong path to successful self-hosting. From here, feel free to explore n8n's official documentation for advanced orchestration features, community-created “nodes,” or deeper integrations like connecting your local code base to n8n’s triggers.

If you want to dive even deeper, consider:

• Creating custom node types in n8n for your unique APIs.

• Scaling n8n with multiple workers for distributed workloads.

• Combining n8n with advanced authentication and API gateway setups.

With n8n at your disposal, you have a powerful platform for connecting and automating all sorts of systems. Enjoy your new setup, and happy automating!