Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Update docker readme #13268

Merged
merged 6 commits into from
Feb 19, 2025
Merged

docs: Update docker readme #13268

Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f04ebcc
docker instructions update
evilnick Feb 14, 2025
c2f0114
more radical re-write
evilnick Feb 14, 2025
cc049df
postgresql
evilnick Feb 14, 2025
ce641a3
link back to docs
evilnick Feb 14, 2025
685471c
remove old screenshot
evilnick Feb 14, 2025
77d4400
Updates per review
evilnick Feb 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
246 changes: 139 additions & 107 deletions docker/images/n8n/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,111 +1,108 @@
![n8n.io - Workflow Automation](https://user-images.githubusercontent.com/65276001/173571060-9f2f6d7b-bac0-43b6-bdb2-001da9694058.png)

# n8n - Workflow automation tool
# n8n - Secure Workflow Automation for Technical Teams

n8n is an extendable workflow automation tool. With a [fair-code](https://faircode.io) distribution model, n8n will always have visible source code, be available to self-host, and allow you to add your own custom functions, logic and apps. n8n's node-based approach makes it highly versatile, enabling you to connect anything to everything.
n8n is a workflow automation platform that gives technical teams the flexibility of code with the speed of no-code. With 400+ integrations, native AI capabilities, and a fair-code license, n8n lets you build powerful automations while maintaining full control over your data and deployments.

<a href="https://raw.githubusercontent.com/n8n-io/n8n/master/assets/n8n-screenshot.png"><img src="https://raw.githubusercontent.com/n8n-io/n8n/master/assets/n8n-screenshot.png" alt="n8n.io - Screenshot"></a>
![n8n.io - Screenshot](https://raw.githubusercontent.com/n8n-io/n8n/master/assets/n8n-screenshot-readme.png)

## Key Capabilities

- **Code When You Need It**: Write JavaScript/Python, add npm packages, or use the visual interface
- **AI-Native Platform**: Build AI agent workflows based on LangChain with your own data and models
- **Full Control**: Self-host with our fair-code license or use our [cloud offering](https://app.n8n.cloud/login)
- **Enterprise-Ready**: Advanced permissions, SSO, and air-gapped deployments
- **Active Community**: 400+ integrations and 900+ ready-to-use [templates](https://n8n.io/workflows)

## Contents

- [n8n - Workflow automation tool](#n8n---workflow-automation-tool)
- [Contents](#contents)
- [Demo](#demo)
- [Available integrations](#available-integrations)
- [Documentation](#documentation)
- [Start n8n in Docker](#start-n8n-in-docker)
- [Start with tunnel](#start-with-tunnel)
- [Persist data](#persist-data)
- [Start with other Database](#start-with-other-database)
- [Use with PostgresDB](#use-with-postgresdb)
- [Passing Sensitive Data via File](#passing-sensitive-data-via-file)
- [Example Setup with Lets Encrypt](#example-setup-with-lets-encrypt)
- [Updating a running docker-compose instance](#updating-a-running-docker-compose-instance)
- [Setting Timezone](#setting-timezone)
- [Build Docker-Image](#build-docker-image)
- [What does n8n mean and how do you pronounce it?](#what-does-n8n-mean-and-how-do-you-pronounce-it)
- [Support](#support)
- [Jobs](#jobs)
- [Upgrading](#upgrading)
- [License](#license)
- [Key Capabilities](#key-capabilities)
- [Contents](#contents)
- [Demo](#demo)
- [Available integrations](#available-integrations)
- [Documentation](#documentation)
- [Start n8n in Docker](#start-n8n-in-docker)
- [Start n8n with tunnel](#start-n8n-with-tunnel)
- [Use with PostgreSQL](#use-with-postgresql)
- [Passing sensitive data using files](#passing-sensitive-data-using-files)
- [Example server setups](#example-server-setups)
- [Updating](#updating)
- [Pull latest (stable) version](#pull-latest-stable-version)
- [Pull specific version](#pull-specific-version)
- [Pull next (unstable) version](#pull-next-unstable-version)
- [Updating with Docker Compose](#updating-with-docker-compose)
- [Setting Timezone](#setting-timezone)
- [Build Docker-Image](#build-docker-image)
- [What does n8n mean and how do you pronounce it?](#what-does-n8n-mean-and-how-do-you-pronounce-it)
- [Support](#support)
- [Jobs](#jobs)
- [License](#license)

## Demo

[:tv: A short video (< 4 min)](https://www.youtube.com/watch?v=RpjQTGKm-ok) that goes over key concepts of creating workflows in n8n.
This [:tv: short video (< 4 min)](https://www.youtube.com/watch?v=RpjQTGKm-ok) goes over key concepts of creating workflows in n8n.

## Available integrations

n8n has 200+ different nodes to automate workflows. The list can be found on: [https://n8n.io/nodes](https://n8n.io/nodes)
n8n has 200+ different nodes to automate workflows. A full list can be found at [https://n8n.io/nodes](https://n8n.io/nodes).

## Documentation

The official n8n documentation can be found under: [https://docs.n8n.io](https://docs.n8n.io)
The official n8n documentation can be found at [https://docs.n8n.io](https://docs.n8n.io).

Additional information and example workflows on the n8n.io website: [https://n8n.io](https://n8n.io)
Additional information and example workflows are available on the website at [https://n8n.io](https://n8n.io).

## Start n8n in Docker

In the terminal, enter the following:

```bash
docker volume create n8n_data

docker run -it --rm \
--name n8n \
-p 5678:5678 \
-v ~/.n8n:/home/node/.n8n \
-v n8n_data:/home/node/.n8n \
docker.n8n.io/n8nio/n8n
```

This command will download all required n8n images and start your container.
You can then access n8n by opening:
[http://localhost:5678](http://localhost:5678)

## Start with tunnel
To save your work between container restarts, it also mounts a docker volume, `n8n_data`. The workflow data gets saved in an SQLite database in the user folder (`/home/node/.n8n`). This folder also contains important data like the webhook URL and the encryption key used for securing credentials.

> **WARNING**: This is only meant for local development and testing. Should not be used in production!
If this data can't be found at startup n8n automatically creates a new key and any existing credentials can no longer be decrypted.

To be able to use webhooks which all triggers of external services like Github
rely on n8n has to be reachable from the web. To make that easy n8n has a
special tunnel service (uses this code: [https://github.com/n8n-io/localtunnel](https://github.com/n8n-io/localtunnel)) which redirects requests from our servers to your local
n8n instance.
## Start n8n with tunnel

> **WARNING**: This is only meant for local development and testing and should **NOT** be used in production!

n8n must be reachable from the internet to make use of webhooks - essential for triggering workflows from external web-based services such as GitHub. To make this easier, n8n has a special tunnel service which redirects requests from our servers to your local n8n instance. You can inspect the code running this service here: [https://github.com/n8n-io/localtunnel](https://github.com/n8n-io/localtunnel)

To use it simply start n8n with `--tunnel`

```bash
docker volume create n8n_data

docker run -it --rm \
--name n8n \
-p 5678:5678 \
-v ~/.n8n:/home/node/.n8n \
-v n8n_data:/home/node/.n8n \
docker.n8n.io/n8nio/n8n \
start --tunnel
```

## Persist data

The workflow data gets by default saved in an SQLite database in the user
folder (`/home/node/.n8n`). That folder also additionally contains the
settings like webhook URL and encryption key.
Note that the folder needs to be writable by user with UID/GID 1000.

```bash
docker run -it --rm \
--name n8n \
-p 5678:5678 \
-v ~/.n8n:/home/node/.n8n \
docker.n8n.io/n8nio/n8n
```

### Start with other Database
## Use with PostgreSQL

By default n8n uses SQLite to save credentials, past executions and workflows.
n8n however also supports PostgresDB.
By default, n8n uses SQLite to save credentials, past executions and workflows. However, n8n also supports using PostgreSQL.

It is important to still persist the data in the `/home/node/.n8n` folder. The reason
is that it contains n8n user data. That is the name of the webhook
(in case) the n8n tunnel gets used and even more important the encryption key
for the credentials. If none gets found n8n creates automatically one on
startup. In case credentials are already saved with a different encryption key
it can not be used anymore as encrypting it is not possible anymore.
Note that even when using a different database, it is still important to
persist the `/home/node/.n8n` folder, which also contains essential n8n
user data including the encryption key for the credentials.

#### Use with PostgresDB

Replace the following placeholders with the actual data:
In the following commands, replace these placeholders with the actual data:

- POSTGRES_DATABASE
- POSTGRES_HOST
Expand All @@ -115,6 +112,8 @@ Replace the following placeholders with the actual data:
- POSTGRES_SCHEMA

```bash
docker volume create n8n_data

docker run -it --rm \
--name n8n \
-p 5678:5678 \
Expand All @@ -125,18 +124,15 @@ docker run -it --rm \
-e DB_POSTGRESDB_USER=<POSTGRES_USER> \
-e DB_POSTGRESDB_SCHEMA=<POSTGRES_SCHEMA> \
-e DB_POSTGRESDB_PASSWORD=<POSTGRES_PASSWORD> \
-v ~/.n8n:/home/node/.n8n \
-v n8n_data:/home/node/.n8n \
docker.n8n.io/n8nio/n8n
```

A full working setup with docker-compose can be found [here](https://github.com/n8n-io/n8n-hosting/blob/main/docker-compose/withPostgres/README.md)
A full working setup with docker-compose can be found [here](https://github.com/n8n-io/n8n-hosting/blob/main/docker-compose/withPostgres/README.md).

## Passing Sensitive Data via File
## Passing sensitive data using files

To avoid passing sensitive information via environment variables "\_FILE" may be
appended to some environment variables. It will then load the data from a file
with the given name. That makes it possible to load data easily from
Docker and Kubernetes secrets.
To avoid passing sensitive information via environment variables, "\_FILE" may be appended to some environment variable names. n8n will then load the data from a file with the given name. This makes it possible to load data easily from Docker and Kubernetes secrets.

The following environment variables support file input:

Expand All @@ -147,37 +143,87 @@ The following environment variables support file input:
- DB_POSTGRESDB_USER_FILE
- DB_POSTGRESDB_SCHEMA_FILE

## Example Setup with Lets Encrypt
## Example server setups

A basic step by step example setup of n8n with docker-compose and Lets Encrypt is available on the
[Server Setup](https://docs.n8n.io/#/server-setup) page.
Example server setups for a range of cloud providers and scenarios can be found in the [Server Setup documentation](https://docs.n8n.io/hosting/installation/server-setups/).

## Updating a running docker-compose instance
## Updating

1. Pull the latest version from the registry
Before you upgrade to the latest version make sure to check here if there are any breaking changes which may affect you: [Breaking Changes](https://github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md)

`docker pull docker.n8n.io/n8nio/n8n`
From your Docker Desktop, navigate to the Images tab and select Pull from the context menu to download the latest n8n image.

2. Stop the current setup
You can also use the command line to pull the latest, or a specific version:

### Pull latest (stable) version

```bash
docker pull docker.n8n.io/n8nio/n8n
```

`sudo docker-compose stop`
### Pull specific version

3. Delete it (will only delete the docker-containers, data is stored separately)
```bash
docker pull docker.n8n.io/n8nio/n8n:0.220.1
```

`sudo docker-compose rm`
### Pull next (unstable) version

4. Then start it again
```bash
docker pull docker.n8n.io/n8nio/n8n:next
```

`sudo docker-compose up -d`
Stop the container and start it again:

## Setting Timezone
1. Get the container ID:

To define the timezone n8n should use, the environment variable `GENERIC_TIMEZONE` can
be set. One instance where this variable is implemented is in the Schedule node. Furthermore, the system's timezone can be set separately,
which controls the output of certain scripts and commands such as `$ date`. The system timezone can be set via
the environment variable `TZ`.
```bash
docker ps -a
```

Example to use the same timezone for both:
2. Stop the container with ID container_id:

```bash
docker stop [container_id]
```

3. Remove the container with ID container_id:


```bash
docker rm [container_id]
```

4. Start the new container:

```bash
docker run --name=[container_name] [options] -d docker.n8n.io/n8nio/n8n
```

### Updating with Docker Compose

If you run n8n using a Docker Compose file, follow these steps to update n8n:

```bash
# Pull latest version
docker compose pull

# Stop and remove older version
docker compose down

# Start the container
docker compose up -d
```

## Setting the timezone

To specify the timezone n8n should use, the environment variable `GENERIC_TIMEZONE` can
be set. One instance where this variable is implemented is in the Schedule node.

The system's timezone can be set separately with the environment variable `TZ`.
This controls the output of certain scripts and commands such as `$ date`.

For example, to use the same timezone for both:

```bash
docker run -it --rm \
Expand All @@ -188,6 +234,8 @@ docker run -it --rm \
docker.n8n.io/n8nio/n8n
```

For more information on configuration and environment variables, please see the [n8n documentation](https://docs.n8n.io/hosting/configuration/environment-variables/).

## Build Docker-Image

```bash
Expand All @@ -201,33 +249,17 @@ docker buildx build --platform linux/amd64,linux/arm64 --build-arg N8N_VERSION=1

**Short answer:** It means "nodemation" and it is pronounced as n-eight-n.

**Long answer:** I get that question quite often (more often than I expected)
so I decided it is probably best to answer it here. While looking for a
good name for the project with a free domain I realized very quickly that all the
good ones I could think of were already taken. So, in the end, I chose
nodemation. "node-" in the sense that it uses a Node-View and that it uses
Node.js and "-mation" for "automation" which is what the project is supposed to help with.
However, I did not like how long the name was and I could not imagine writing
something that long every time in the CLI. That is when I then ended up on
"n8n". Sure does not work perfectly but does neither for Kubernetes (k8s) and
did not hear anybody complain there. So I guess it should be ok.
**Long answer:** I get that question quite often (more often than I expected) so I decided it is probably best to answer it here. While looking for a good name for the project with a free domain I realized very quickly that all the good ones I could think of were already taken. So, in the end, I chose nodemation. "node-" in the sense that it uses a Node-View and that it uses Node.js and "-mation" for "automation" which is what the project is supposed to help with.
However, I did not like how long the name was and I could not imagine writing something that long every time in the CLI. That is when I then ended up on "n8n". Sure it does not work perfectly but neither does it for Kubernetes (k8s) and I did not hear anybody complain there. So I guess it should be ok.

## Support

If you have problems or questions go to our forum, we will then try to help you asap:

[https://community.n8n.io](https://community.n8n.io)
If you need more help with n8n, you can ask for support in the [n8n community forum](https://community.n8n.io). This is the best source of answers, as both the n8n support team and community members can help.

## Jobs

If you are interested in working for n8n and so shape the future of the project
check out our [job posts](https://apply.workable.com/n8n/)

## Upgrading

Before you upgrade to the latest version make sure to check here if there are any breaking changes which concern you:
[Breaking Changes](https://github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md)
If you are interested in working for n8n and so shape the future of the project check out our [job posts](https://jobs.ashbyhq.com/n8n).

## License

You can find the license information [here](https://github.com/n8n-io/n8n/blob/master/README.md#license)
You can find the license information [here](https://github.com/n8n-io/n8n/blob/master/README.md#license).
Loading