How to self-host n8n framework?

Last update: May 23, 2025 - by Saulius

blog n8n integrations genAI

Summary

This is step by step tutorial to self-host one of the most popular open source workflow automation frameworks - n8n. We discuss n8n internals, hosting options and requirements for self hosting this application. With practical examples.

n8n

n8n is an open source automation platform, which provides hundreds of prebuilt integration connectors to the multiple cloud endpoints, tools and systems.

It's available as a Community Edition version as well as an Enterprise edition, with the additional functionality.

This framework operates the concept of workflows, which include one or more orchestrated integration steps and can be triggered by the multiple event sources.

n8n provides a great UI visualization of these workflows, together with the low code UI interface to edit them. Below is a simple example of such workflow.

As an open source project n8n has drawn a very large community of adopters and contributors who created and maintain thousands of workflow examples available to reuse.

n8n under the hood

This tutorial focuses on the open source, Community Edition.

n8n is a TypeScript application, which runs in the Node.js runtime environment.

It is using database to store credentials, execution data, workflow configurations. By default database is SQLite. PostgreSQL database is also officially supported as an option.

If you have Node.js runtime on your local machine, you can simply use npm package manager to install and run n8n as a global Node.js package.

# install the latest version of n8n package
npm install n8n -g
# install the specific version of n8n
npm install [email protected] -g
# update to it to the newer versions
npm update n8n -g
# start n8n
n8n start

# shell output
Editor is now accessible via:
http://localhost:5678

The NPM module starts the inbuilt web server, on the specific port which you will see printed out in the shell.

You can pass settings and configuration options to n8n as the environment variables before starting the application.

Alternatively you can provide settings in the configuration file (one or multiple configuration files are supported), which will be loaded by n8n at startup.

See some examples below:

# example n8n configuration options provided as env variables
N8N_DIAGNOSTICS_ENABLED=false
N8N_VERSION_NOTIFICATIONS_ENABLED=false
N8N_TEMPLATES_ENABLED=false
N8N_LOG_LEVEL="debug"
N8N_ENCRYPTION_KEY="randomstring"
N8N_PORT="8003"

# path to single configuration file
N8N_CONFIG_FILES=/path/n8n-config.json
# path to multiple configuration files
N8N_CONFIG_FILES=/path/config1.json,/path/config2.json

n8n execution mode

Execution mode defines how n8n application runs.

2 execution modes are supported. regular which means single main n8n instance, which runs with single DB and handles all workflows itself.

And the queue mode, which allows multiple main instances and multiple worker nodes running with main database (SQLite or PostgreSQL) and Redis db instance as queue.

Execution mode is controlled with EXECUTIONS_MODE environment variable, with regular as default.

Running n8n with Docker

Running n8n as NPM package works great for testing and sandbox type environments.

As you move on to more stable setups, running n8n within Docker container is a recommended best practice.

See the below commands to start n8n container.

# Run container from official Docker image
docker run -p 8001:5678 docker.n8n.io/n8nio/n8n
# Run container with n8n data persisted in working directory
docker run -p 8001:5678 -v $(pwd)/n8n_data:/home/node/.n8n \
docker.n8n.io/n8nio/n8n

By visiting a container url and the port, you will be greeted with the n8n registration screen.

n8n registration screen at startup local hosting

After completing the initial new owner user registration form and the additional questionaire, you will get to the actual n8n home page.

n8n home screen after registration is complete

You can now start building or importing n8n automated workflows. See our other tutorials on how this is done.

Auto registering n8n owner user

Note: the new registration screen will be shown to user every time the new Docker container is started. n8n doesn't provide us with an option to automatically provision the owner user during startup time.

How can you skip the initial n8n registration screens?

The solution we apply in the automated new n8n container spin ups - reusing saved SQLite database file with already registered owner user.

Run the container by mounting local directory (see code example in above section).
Register the user.
Save the data from local directory n8n_data which will now include the database file database.sqlite.

Next time you run new container setup, mount the same data directory which will be reused by n8n.

New registration screens will be gone - you can use previous user credentials to login.

# Reuse the n8n data directory 
docker run -p 8001:5678 -v $(pwd)/n8n_data:/home/node/.n8n \
docker.n8n.io/n8nio/n8n

Running n8n with Docker Compose

As a last step in this tutorial, we will use Docker Compose to orchestrate the n8n container run.

Docker Compose gives an additional advantages over manually running Docker containers - simple orchestration, automatic container restarts, scalability if needed.

Create the docker-compose.yml file with the following configuration.

version: '3.8'
services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    restart: always
    environment:
      - N8N_DIAGNOSTICS_ENABLED=false
      - N8N_VERSION_NOTIFICATIONS_ENABLED=false
      - N8N_LOG_LEVEL=debug
    ports:
      - :5678:5678
    volumes:
      - ./n8n_data:/home/node/.n8n

Pay attention to the volumes section where we mount local n8n_data directory with the preregistered owner user, as describer in the previous tutorial section.

Start the Docker Compose.

# start docker compose
docker-compose up

Conclusion

The above steps will help you to get n8n up and running on your local dev machine.

There are few options to run 8n8 framework and we cover all of them. We are using Docker Compose based setup in the next tutorial parts - mainly for hosting your own VPS service with n8n / nginx and automating the workflow deployments.

Visit other tutorial parts to learn more.

Finally, here are some relevant resources / references which you will find useful: