This page is an overview of how n8n is configured and deployed across its supported runtime modes and infrastructure environments. It covers the configuration system, CLI commands, Docker packaging, task runner deployment, license management, and observability.
For detailed coverage of each topic, see the child pages:
GlobalConfig, env var mappings, FrontendSettingsstart, worker, webhook commands and boot lifecycleTaskBrokerServiceLicense class, feature flags, auto-renewalEventService, telemetry relays, SentryAll runtime configuration is centralized in the @n8n/config package. The root class is GlobalConfig, declared in packages/@n8n/config/src/index.ts which composes roughly 35 nested configuration sub-classes, each mapping directly to environment variables via three decorators:
| Decorator | Role |
|---|---|
@Config | Marks a class as a DI-managed config node |
@Env('ENV_VAR_NAME') | Binds a property to a specific environment variable |
@Nested | Composes a sub-config class into the parent |
GlobalConfig is registered with @n8n/di (the in-house dependency injection container), so any service can receive it via constructor injection.
GlobalConfig composition ā selected nested classes:
| Property | Class | Key environment variables |
|---|---|---|
database | DatabaseConfig | DB_TYPE, DB_POSTGRESDB_HOST, DB_POSTGRESDB_USER |
executions | ExecutionsConfig | EXECUTIONS_MODE, EXECUTIONS_TIMEOUT |
taskRunners | TaskRunnersConfig | N8N_RUNNERS_MODE, N8N_RUNNERS_ENABLED |
license | LicenseConfig | N8N_LICENSE_SERVER_URL, N8N_LICENSE_ACTIVATION_KEY |
security | SecurityConfig | N8N_BLOCK_FILE_ACCESS_TO_N8N_FILES |
endpoints | EndpointsConfig | N8N_ENDPOINT_REST, N8N_METRICS |
queue | ScalingModeConfig | QUEUE_BULL_REDIS_HOST, QUEUE_BULL_REDIS_PORT |
logging | LoggingConfig | N8N_LOG_LEVEL, N8N_LOG_OUTPUT |
sso | SsoConfig | N8N_SSO_SAML_ENABLED, N8N_SSO_OIDC_ENABLED |
diagnostics | DiagnosticsConfig | N8N_DIAGNOSTICS_ENABLED |
_FILE variants are supported for any @Env-mapped property. If DB_POSTGRESDB_PASSWORD_FILE is set, the system reads the file contents as the value, trimming whitespace and warning if any is detected. See packages/@n8n/config/test/config.test.ts500-541
A legacy convict-based schema in packages/cli/src/config/schema.ts exists for a small number of mutable runtime properties (authentication method, internal state). New configuration must not be added there.
GlobalConfig class hierarchy:
Sources: packages/@n8n/config/src/index.ts packages/@n8n/config/test/config.test.ts
n8n runs as one of three process types, each launched via a dedicated CLI command defined in packages/cli/src/commands/:
| Command class | CLI invocation | Process role |
|---|---|---|
Start | n8n start | Main process: HTTP server, workflow activation, REST API, UI serving |
Worker | n8n worker | Queue worker: BullMQ job consumer, no HTTP server |
Webhook | n8n webhook | Webhook-only process: production webhook handler, requires queue mode |
All three extend BaseCommand, which handles shared initialization: database connection, node loading, binary data service, task runner setup, and crash journal management.
executions.mode in GlobalConfig/ExecutionsConfig is the key setting that determines how processes collaborate:
regular ā single-process, all execution happens in the main processqueue ā distributed mode; workers pick up jobs from BullMQ via RedisProcess startup flow:
Sources: packages/cli/src/commands/start.ts packages/cli/src/commands/worker.ts packages/cli/src/commands/webhook.ts
FrontendService (in packages/cli/src/services/frontend.service.ts) assembles the FrontendSettings object that is served to the Vue SPA on every authenticated page load. It reads from GlobalConfig, the License service, InstanceSettings, and various other services.
The FrontendSettings type is defined in packages/@n8n/api-types/src/frontend-settings.ts. It includes:
false, set to true when license permits)A PublicFrontendSettings subset is served to unauthenticated routes (login page) and intentionally omits anything that requires authentication context.
Settings derivation:
Sources: packages/cli/src/services/frontend.service.ts packages/@n8n/api-types/src/frontend-settings.ts
Three Docker images are produced from this repository:
| Image | Dockerfile | Purpose |
|---|---|---|
n8nio/n8n | docker/images/n8n/Dockerfile | Main n8n application |
n8nio/runners | docker/images/runners/Dockerfile | Task runner sidecar (Alpine) |
n8nio/runners (distroless) | docker/images/runners/Dockerfile.distroless | Task runner sidecar (security-hardened) |
The base image for the main n8n image is n8nio/base (built from docker/images/n8n-base/Dockerfile), which is an Alpine-based Node image including git, openssh, graphicsmagick, tini, and tzdata.
Docker build pipeline:
The main image's docker-entrypoint.sh runs as the node user on port 5678. The runners image runs as a runner user on port 5680. The task-runner-launcher binary (downloaded at image build time) is the entrypoint for the runners sidecar.
Multi-arch builds (AMD64 + ARM64) are assembled via docker buildx imagetools create manifests in docker-build-push.yml. SLSA L3 provenance attestation and VEX attestation via cosign are applied to stable, RC, and nightly releases.
Sources: docker/images/n8n/Dockerfile docker/images/runners/Dockerfile docker/images/runners/Dockerfile.distroless docker/images/n8n-base/Dockerfile .github/workflows/docker-build-push.yml scripts/build-n8n.mjs
When taskRunners.mode is internal (default), the main n8n process spawns JS and Python runner subprocesses. When set to external, the runners run as a separate sidecar container (n8nio/runners) and connect to n8n's task broker over WebSocket.
Runner configuration in GlobalConfig:
| Config property | Env var | Default | Purpose |
|---|---|---|---|
taskRunners.enabled | N8N_RUNNERS_ENABLED | true | Enable/disable task runners |
taskRunners.mode | N8N_RUNNERS_MODE | internal | internal or external |
taskRunners.port | N8N_RUNNERS_PORT | 5679 | Broker WebSocket port |
taskRunners.authToken | N8N_RUNNERS_AUTH_TOKEN | '' | Shared secret for runner auth |
taskRunners.maxConcurrency | N8N_RUNNERS_MAX_CONCURRENCY | 10 | Max parallel tasks per runner |
taskRunners.taskTimeout | N8N_RUNNERS_TASK_TIMEOUT | 300 | Task timeout in seconds |
The runners sidecar reads its runner definitions from /etc/n8n-task-runners.json (copied at image build time from docker/images/runners/n8n-task-runners.json). This file specifies the command, arguments, health-check port, and allowed environment variables for each runner type (javascript, python).
Sources: packages/@n8n/config/test/config.test.ts272-286 docker/images/runners/n8n-task-runners.json docker/images/runners/README.md
The License class in packages/cli/src/license.ts wraps the @n8n_io/license-sdk LicenseManager. It:
SETTINGS_LICENSE_CERT_KEY) or from GlobalConfig.license.cert (ephemeral mode)GlobalConfig.license.serverUrl (https://license.n8n.io/v1 by default) for auto-renewalisLicensed(feature: BooleanLicenseFeature) and numeric quota reads via getValue(feature)Feature flags are defined as string constants in @n8n/constants:
LICENSE_FEATURES.SHARING ā 'feat:sharing'
LICENSE_FEATURES.SAML ā 'feat:saml'
LICENSE_FEATURES.SOURCE_CONTROL ā 'feat:sourceControl'
LICENSE_FEATURES.VARIABLES ā 'feat:variables'
...
LicenseState in packages/@n8n/backend-common/src/license-state.ts provides a typed wrapper used by controllers and services as the preferred way to check feature availability (the License methods are progressively being deprecated in its favor).
Sources: packages/cli/src/license.ts packages/@n8n/constants/src/index.ts packages/@n8n/backend-common/src/license-state.ts
n8n's internal event system is built around EventService, which emits typed events from RelayEventMap. Two primary relays consume these events:
TelemetryEventRelay ā forwards events to RudderStack/PostHog via the Telemetry serviceLogStreamingEventRelay ā forwards events to the MessageEventBus for external log streaming destinationsSentry error reporting is configured via GlobalConfig.sentry:
backendDsn ā used by the Node.js processfrontendDsn ā forwarded to the browser via FrontendSettings / Start.generateConfigTags()The Start command encodes the Sentry frontend config as a base64 <meta> tag injected into index.html at startup time via generateStaticAssets(). See packages/cli/src/commands/start.ts123-142
Sources: packages/cli/src/commands/start.ts123-188 packages/cli/src/services/frontend.service.ts163-179
The complete default configuration object is documented in the config test file. Selected important defaults:
| Setting | Default | Env var |
|---|---|---|
| Host | localhost | N8N_HOST |
| Port | 5678 | N8N_PORT |
| Protocol | http | N8N_PROTOCOL |
| Database type | sqlite | DB_TYPE |
| Execution mode | regular | EXECUTIONS_MODE |
| Log level | info | N8N_LOG_LEVEL |
| Timezone | America/New_York | GENERIC_TIMEZONE |
| License server | https://license.n8n.io/v1 | N8N_LICENSE_SERVER_URL |
| Execution timeout | -1 (disabled) | EXECUTIONS_TIMEOUT |
| Execution pruning | enabled, 336h max age, 10,000 max count | EXECUTIONS_DATA_PRUNE etc. |
| Task runner mode | internal | N8N_RUNNERS_MODE |
| Webhook endpoint | webhook | N8N_ENDPOINT_WEBHOOK |
| REST endpoint | rest | N8N_ENDPOINT_REST |
| Metrics | disabled | N8N_METRICS |
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.