Configuration Management

Relevant source files

The following files were used as context for generating this wiki page:

• docker/images/n8n/README.md
• packages/frontend/@n8n/stores/src/tests/metaTagConfig.test.ts
• CONTRIBUTING.md
• packages/testing/playwright/tests/cli-workflows/README.md
• CLAUDE.md
• packages/@n8n/create-node/README.md
• packages/frontend/editor-ui/src/constants.ts

Configuration in n8n is managed through a combination of environment variables, configuration files, and frontend-specific mechanisms. This system is designed to be flexible, supporting various deployment scenarios from local development to production Docker containers. The core of the backend configuration is centralized in the @n8n/config package, which is consumed by other parts of the application, such as the CLI.

For frontend applications, configuration is passed from the server-rendered HTML to the client-side application using <meta> tags. This decouples the frontend from direct access to backend environment variables, providing a secure and organized way to supply necessary settings.

Backend Configuration

The backend configuration is primarily driven by environment variables, making it well-suited for containerized environments like Docker. It also supports file-based secrets for enhanced security.

Environment Variables

n8n uses environment variables to configure database connections, server settings, and other operational parameters. These are particularly important when running n8n via Docker.

The following diagram illustrates the flow of configuration from its source to the application.

This diagram shows that the n8n application sources its configuration from environment variables, file-based secrets, and a local configuration file.
Sources: docker/images/n8n/README.md, packages/testing/playwright/tests/cli-workflows/README.md

Key Environment Variables

The following table lists some of the key environment variables used for configuration.

Variable	Description	Example
DB_TYPE	Specifies the database type. Defaults to sqlite.	postgresdb
DB_POSTGRESDB_HOST	The hostname of the PostgreSQL server.	<POSTGRES_HOST>
DB_POSTGRESDB_DATABASE	The name of the PostgreSQL database.	<POSTGRES_DATABASE>
DB_POSTGRESDB_USER	The username for the PostgreSQL connection.	<POSTGRES_USER>
DB_POSTGRESDB_PASSWORD	The password for the PostgreSQL connection.	<POSTGRES_PASSWORD>
DB_POSTGRESDB_SCHEMA	The schema to use within the PostgreSQL database.	<POSTGRES_SCHEMA>
GENERIC_TIMEZONE	Sets the timezone for the n8n application logic (e.g., Schedule node).	Europe/Berlin
TZ	Sets the system's timezone, affecting script outputs like $ date.	Europe/Berlin
N8N_ENCRYPTION_KEY	The key used to encrypt and decrypt credentials.	YOUR_KEY_FROM_BITWARDEN

Sources: docker/images/n8n/README.md, packages/testing/playwright/tests/cli-workflows/README.md

File-based Secrets

To avoid passing sensitive data directly through environment variables, n8n supports a file-based mechanism. By appending _FILE to certain environment variable names, the application will read the value from the specified file path. This is useful for integrating with Docker Secrets or Kubernetes Secrets.

Supported variables include:

• DB_POSTGRESDB_DATABASE_FILE
• DB_POSTGRESDB_HOST_FILE
• DB_POSTGRESDB_PASSWORD_FILE
• DB_POSTGRESDB_PORT_FILE
• DB_POSTGRESDB_USER_FILE
• DB_POSTGRESDB_SCHEMA_FILE

Sources: docker/images/n8n/README.md

Local Development Configuration

For local development, some configuration can be managed via files and environment variables.

• ~/.n8n/config: A local JSON file can be used to store settings like the N8N_ENCRYPTION_KEY. This is particularly useful for the testing framework.
• N8N_DEV_RELOAD=true: An environment variable that enables hot-reloading for custom node development, automatically detecting changes without a server restart.

Sources: packages/testing/playwright/tests/cli-workflows/README.md, CONTRIBUTING.md

Frontend Configuration

The frontend application (editor-ui) receives its configuration from the backend during the initial page load. This is accomplished by embedding configuration data within <meta> tags in the HTML document.

Meta Tag Mechanism

The backend renders the main HTML page and injects configuration values into <meta> tags. The client-side JavaScript then reads these tags to bootstrap its own configuration state.

The process is as follows:

1. The backend encodes a configuration value (often a JSON string) into Base64.
2. This Base64 string is set as the content attribute of a <meta> tag.
3. The <meta> tag's name attribute follows the pattern n8n:config:${configName}.
4. The frontend uses helper functions to find the tag by name, read the content, decode it from Base64, and parse it (if it's JSON).

The following sequence diagram shows this process.

This diagram illustrates the frontend retrieving its configuration from meta tags injected by the backend.
Sources: packages/frontend/@n8n/stores/src/tests/metaTagConfig.test.ts

Helper Functions

The logic for reading configuration from meta tags is encapsulated in two primary functions.

Function	Description	Return Value
getConfigFromMetaTag(configName)	Finds a meta tag by n8n:config:${configName}, reads its content, and decodes it from Base64.	A string, or null if the tag is not found, content is empty, or decoding fails.
getAndParseConfigFromMetaTag<T>(configName)	Calls getConfigFromMetaTag and then attempts to JSON.parse the resulting string.	A parsed object of type T, or null if any step fails.

Sources: packages/frontend/@n8n/stores/src/tests/metaTagConfig.test.ts:1-200

The creation of these meta tags is tested using a helper function, which demonstrates how they are structured in the document's <head>.

// packages/frontend/@n8n/stores/src/__tests__/metaTagConfig.test.ts:10-19
function createMetaTag(configName: string, content?: string): void {
  const metaTag = document.createElement('meta');
  metaTag.setAttribute('name', `n8n:config:${configName}`);

  if (content !== undefined) {
    metaTag.setAttribute('content', content);
  }

  document.head.appendChild(metaTag);
}

This test helper shows that a meta tag is created with a name like n8n:config:testConfig and its content is set.
Sources: packages/frontend/@n8n/stores/src/tests/metaTagConfig.test.ts:10-19

Application Constants

The n8n frontend relies on a set of hardcoded constants for various features, limits, and identifiers. These are defined in packages/frontend/editor-ui/src/constants.ts and are used throughout the UI.

Key Constants

Constant	Value	Description
MAX_WORKFLOW_SIZE	1024 * 1024 * 16	16 MB limit for workflow size.
MAX_PINNED_DATA_SIZE	1024 * 1024 * 12	12 MB limit for pinned data in a workflow.
NEW_WORKFLOW_ID	'new'	Identifier for a new, unsaved workflow.
DEFAULT_NEW_WORKFLOW_NAME	'My workflow'	The default name for a new workflow.
DOCS_DOMAIN	'docs.n8n.io'	The base domain for documentation links.
WEBHOOK_NODE_TYPE	'n8n-nodes-base.webhook'	The unique type identifier for the Webhook node.
HTTP_REQUEST_NODE_TYPE	'n8n-nodes-base.httpRequest'	The unique type identifier for the HTTP Request node.
LOCAL_STORAGE_THEME	'N8N_THEME'	The key used in local storage to save the user's theme preference.
LOCAL_STORAGE_EXPERIMENT_OVERRIDES	'N8N_EXPERIMENT_OVERRIDES'	The local storage key for overriding feature flags/experiments.

Sources: packages/frontend/editor-ui/src/constants.ts