Skip to content

Commit f953c80

Browse files
ivovivov
authored
docs: Update docs for multi-language lifecycle (#72)
1 parent 6466d50 commit f953c80

File tree

4 files changed

+80
-73
lines changed

4 files changed

+80
-73
lines changed

‎README.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,3 @@ CLI utility to launch an [n8n task runner](https://docs.n8n.io/hosting/configura
2727
- [Development](docs/development.md) - how to set up a development environment to work on the launcher
2828
- [Release](docs/release.md) - how to release a new version of the launcher
2929
- [Lifecycle](docs/lifecycle.md) - how the launcher works
30-
- [Environment](docs/environment.md) - how the launcher handles environment variables

‎docs/development.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ To set up a development environment, follow these steps:
44

55
1. Install Go >=1.24.6, [`golangci-lint`](https://golangci-lint.run/welcome/install/) and `make`.
66

7-
2. Clone this repository and create a [config file](setup.md).
7+
2. Clone this repository and create a [config file](setup.md#config-file).
88

99
```sh
1010
git clone https://github.com/n8n-io/task-runner-launcher
@@ -26,14 +26,14 @@ make build
2626
```sh
2727
export N8N_RUNNERS_ENABLED=true
2828
export N8N_RUNNERS_MODE=external
29-
export N8N_RUNNERS_AUTH_TOKEN=... # random string
29+
export N8N_RUNNERS_AUTH_TOKEN=test
3030
pnpm start
3131
```
3232

3333
6. Start launcher:
3434

3535
```sh
36-
export N8N_RUNNERS_AUTH_TOKEN=... # same string as in step 5
36+
export N8N_RUNNERS_AUTH_TOKEN=test
3737
make run
3838
```
3939

‎docs/environment.md

Lines changed: 0 additions & 35 deletions
This file was deleted.

‎docs/setup.md

Lines changed: 77 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,48 @@
11
# Setup
22

3-
This launcher is intended for deployment as a sidecar container alongside one or more n8n instance containers. The launcher exposes a health check endpoint at `/healthz` on port `5680` for liveness checks, and the n8n instance does so on port `5681`. The orchestrator (e.g. k8s) can use this to monitor the health of the launcher and of the n8n instance.
3+
To set up the launcher:
44

5-
1. Download the **launcher binary** from the [releases page](https://github.com/n8n-io/task-runner-launcher/releases).
5+
1. Download the latest launcher binary from the [releases page](https://github.com/n8n-io/task-runner-launcher/releases).
66

7-
2. Create a **config file** on the host at `/etc/n8n-task-runners.json` and make this file accessible to the launcher.
7+
2. Create a [config file](#config-file) on the host and make it accessible to the launcher.
8+
9+
3. Configure [environment variables](#environment-variables).
10+
11+
4. Deploy the launcher as a sidecar container to an n8n main or worker instance, setting the launcher to manage one or multiple runner types.
12+
13+
```sh
14+
./task-runner-launcher javascript # or
15+
./task-runner-launcher javascript python
16+
```
17+
18+
5. Ensure your orchestrator (e.g. k8s) performs regular liveness checks on both launcher and task broker.
19+
20+
- The launcher exposes a health check endpoint at `/healthz` on port `5680`, configurable via `N8N_RUNNERS_LAUNCHER_HEALTH_CHECK_PORT`.
21+
- The task broker exposes a health check endpoint at `/healthz` on port `5679`, configurable via `N8N_RUNNERS_BROKER_PORT`.
22+
23+
```mermaid
24+
sequenceDiagram
25+
participant k8s
26+
participant N8N as n8n main or worker
27+
participant Launcher
28+
participant Runner
29+
Note over N8N: main server: 5678<br/>broker server: 5679
30+
Note over Launcher: health check server: 5680
31+
Note over Runner: health check server: 5681
32+
33+
par k8s health checks
34+
k8s->>Launcher: GET /healthz
35+
and
36+
k8s->>N8N: GET /healthz
37+
end
38+
39+
Launcher->>Runner: GET /healthz
40+
N8N<<->>Runner: ws heartbeat
41+
```
42+
43+
## Config file
44+
45+
Example config file at `/etc/n8n-task-runners.json`:
846

947
```json
1048
{
@@ -14,12 +52,11 @@ This launcher is intended for deployment as a sidecar container alongside one or
1452
"workdir": "/usr/local/bin",
1553
"command": "/usr/local/bin/node",
1654
"args": [
55+
"--disallow-code-generation-from-strings",
56+
"--disable-proto=delete",
1757
"/usr/local/lib/node_modules/n8n/node_modules/@n8n/task-runner/dist/start.js"
1858
],
19-
"allowed-env": [
20-
"PATH",
21-
"GENERIC_TIMEZONE",
22-
],
59+
"allowed-env": ["PATH", "GENERIC_TIMEZONE"],
2360
"env-overrides": {
2461
"N8N_RUNNERS_TASK_TIMEOUT": "80",
2562
"N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT": "120",
@@ -28,41 +65,47 @@ This launcher is intended for deployment as a sidecar container alongside one or
2865
"NODE_FUNCTION_ALLOW_EXTERNAL": "moment",
2966
"NODE_OPTIONS": "--max-old-space-size=4096"
3067
}
68+
},
69+
{
70+
"runner-type": "python",
71+
"workdir": "/usr/local/bin",
72+
"command": "/usr/local/bin/python",
73+
"args": [
74+
"/usr/local/lib/python3.13/site-packages/n8n/task-runner-python/main.py"
75+
],
76+
"allowed-env": ["PATH", "GENERIC_TIMEZONE"],
77+
"env-overrides": {
78+
"N8N_RUNNERS_TASK_TIMEOUT": "30",
79+
"N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT": "30",
80+
"N8N_RUNNERS_MAX_CONCURRENCY": "2"
81+
}
3182
}
3283
]
3384
}
3485
```
3586

36-
Task runner config fields:
37-
38-
- `runner-type` is the type of task runner, currently only `javascript` is supported.
39-
- `workdir` is the path to directory containing the task runner binary.
40-
- `command` is the command to execute in order to start the task runner.
41-
- `args` are the args for the command to execute, currently the path to the task runner entrypoint.
42-
- `allowed-env` and `env-overrides` are env vars that the launcher will pass through to or set directly on the runner, respectively. See [environment](environment.md).
43-
44-
3. Set the **environment variables** for the launcher.
87+
| Property | Description |
88+
| --------------- | ----------------------------------------------------------------------------------------------------------------------- |
89+
| `runner-type` | Type of task runner, e.g. `javascript` or `python`. The launcher can manage only one runner per type. |
90+
| `workdir` | Path where the task runner's `command` will run. |
91+
| `command` | Command to start the task runner. |
92+
| `args` | Args and flags to use with `command`. |
93+
| `allowed-env` | Env vars that the launcher will pass through from its own environment to the runner. See [environment](environment.md). |
94+
| `env-overrides` | Env vars that the launcher will set directly on the runner. See [environment](environment.md). |
4595

46-
- It is required to specify an auth token by setting `N8N_RUNNERS_AUTH_TOKEN` to a secret. The launcher will use this secret to authenticate with the n8n instance. You will also pass this `N8N_RUNNERS_AUTH_TOKEN` to the n8n instance as well.
96+
## Environment variables
4797

48-
- Optionally, specify the launcher's log level by setting `N8N_RUNNERS_LAUNCHER_LOG_LEVEL` to `debug`, `info`, `warn` or `error`. Default is `info`. You can also use `NO_COLOR=1` to disable color output.
98+
It is required to pass `N8N_RUNNERS_AUTH_TOKEN` to the launcher and to the n8n instance. This token will allow the launcher to authenticate with the n8n instance and to obtain a grant tokens for every runner it manages. All other env vars are optional and are listed in the [n8n docs](https://docs.n8n.io/hosting/configuration/environment-variables/task-runners).
4999

50-
- Optionally, specify the launcher's auto-shutdown timeout by setting `N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT` to a number of seconds, or set it to `0` to disable. Default is `15`. The runner will exit after this timeout if it is idle for the specified duration, and will be re-launched on demand when the next task comes in.
100+
The launcher can pass env vars to task runners in two ways, as specified in the [config file](#config-file):
51101

52-
- Optionally, specify the task broker's URI (i.e. n8n instance's URI) by setting `N8N_RUNNERS_TASK_BROKER_URI`. Default is `http://127.0.0.1:5679`.
102+
| Source | Description | Purpose |
103+
|--------|-------------|------------|
104+
| `allowed-env` | Env vars filtered from the launcher's own environment | Passing env vars common to all runner types |
105+
| `env-overrides` | Env vars set by the launcher directly on the runner, with precedence over `allowed-env` | Passing env vars specific to a single runner type |
53106

54-
- Optionally, specify the port for the launcher's health check server by setting `N8N_RUNNERS_LAUNCHER_HEALTH_CHECK_PORT`. Default is `5680`. When overriding this port, be mindful of port conflicts - by default, the n8n instance uses `5678` for its regular server and `5679` for its task broker server, and the runner uses `5681` for its health check server.
107+
Exceptionally, these three env vars cannot be disallowed or overridden:
55108

56-
- Optionally, configure [Sentry error tracking](https://docs.sentry.io/platforms/go/configuration/options/) with these env vars:
57-
- `SENTRY_DSN`
58-
- `DEPLOYMENT_NAME`: Mapped to `ServerName`
59-
- `ENVIRONMENT`: Mapped to `Environment`
60-
- `N8N_VERSION`: Mapped to `Release`
61-
62-
- Optionally, set `N8N_RUNNERS_TASK_TIMEOUT` to specify how long (in seconds) a task may run for before it is aborted. Default is `60`.
63-
64-
4. Run the launcher:
65-
66-
```sh
67-
./task-runner-launcher javascript
68-
```
109+
- `N8N_RUNNERS_TASK_BROKER_URI`
110+
- `N8N_RUNNERS_GRANT_TOKEN`
111+
- `N8N_RUNNERS_HEALTH_CHECK_SERVER_ENABLED=true`

0 commit comments

Comments
 (0)