Comprehensive Guide to Key n8n Configuration Settings
When it comes to workflow automation, n8n is a powerful, self-hosted platform that allows you to build flexible, end-to-end integrations. Much of n8n’s behaviour can be customised through environment variables, making it simpler to tailor your automations to specific business needs. In this guide, we’ll walk through the most important n8n configuration settings in detail, grouped by categories such as deployment, database, execution, security, and more. Whether you’re running n8n in Docker, Kubernetes, or on a local server, these variables will help you optimise your setup.
1. Deployment Settings
These settings control the general deployment parameters for your n8n instance, such as where it’s hosted, how the interface is served, and how new features or updates are handled.
N8N_EDITOR_BASE_URL
- Purpose: Defines the public URL where users can access n8n’s editor interface.
- Why It Matters: Critical for correct redirect flows during OAuth authentication, email notifications with correct links, and any external references that must point back to your instance.
N8N_CONFIG_FILES
- Purpose: Specifies the path to a JSON file that holds configuration values for n8n.
- Usage Tip: Ideal for bulk configuration if you prefer to centralise settings, especially across different environments (development, staging, production).
N8N_DISABLE_UI
- Purpose: When set to
true
, disables the n8n graphical user interface. - Default:
false
- Why Disable?: Useful if you only rely on n8n’s API or have a headless environment where no UI is needed.
N8N_PREVIEW_MODE
- Purpose: Activates a preview or demo mode that typically offers limited functionality.
- Default:
false
- Use Case: Great for demonstrations or trial environments where you don’t want users editing full production settings.
N8N_TEMPLATES_ENABLED
- Purpose: Enables or disables access to official or community-contributed workflow templates.
- Default:
false
- SEO Tip: Encouraging users to leverage these templates can significantly speed up workflow development.
N8N_TEMPLATES_HOST
- Purpose: The URL that n8n uses to fetch pre-built workflow templates.
- Default:
https://api.n8n.io
N8N_ENCRYPTION_KEY
- Purpose: Defines the encryption key used to secure stored credentials in the n8n database.
- Security Note: If you don’t specify one, n8n generates a new key on startup. Make sure this key is backed up if you need to recover encrypted credentials.
N8N_USER_FOLDER
- Purpose: Sets the location of the
.n8n
folder containing user data (e.g., saved workflows, credentials). - Default:
user-folder
- Why It Matters: Adjusting this allows you to separate persistent data from containerised or ephemeral file systems for easier backups or migrations.
N8N_PATH
- Purpose: Defines the URL path under which n8n is accessible.
- Default:
/
- Example: If set to
/automation
, you’d reach n8n atyourdomain.com/automation
.
N8N_HOST
- Purpose: The host on which n8n listens.
- Default:
localhost
- Tip: Change this if you’re exposing n8n externally or using Docker with a specific network.
N8N_PORT
- Purpose: The port for the HTTP server.
- Default:
5678
N8N_LISTEN_ADDRESS
- Purpose: The network interface address (e.g.,
0.0.0.0
for all IPv4 addresses). - Default:
0.0.0.0
N8N_PROTOCOL
- Purpose: Determines whether n8n uses HTTP or HTTPS.
- Default:
http
- Security Note: If you set this to
https
, you must also provide valid certificate paths with the variables below.
N8N_SSL_KEY
and N8N_SSL_CERT
- Purpose: Paths to the SSL/TLS key and certificate files when using HTTPS.
N8N_PERSONALIZATION_ENABLED
- Purpose: Toggles personalised prompts or suggestions during onboarding.
- Default:
true
N8N_VERSION_NOTIFICATIONS_ENABLED
- Purpose: Enables the system that checks for new version notifications.
- Default:
true
N8N_VERSION_NOTIFICATIONS_ENDPOINT
and N8N_VERSION_NOTIFICATIONS_INFO_URL
- Purpose: Points n8n to the API endpoint for updates, and the URL where users can learn more about upgrading.
- Defaults:
- Endpoint:
https://api.n8n.io/versions/
- Info URL:
https://docs.n8n.io/getting-started/installation/updating.html
- Endpoint:
N8N_DIAGNOSTICS_ENABLED
- Purpose: Governs whether n8n can send anonymous telemetry to help the team improve the software.
- Default:
true
- Impact: Turning it off (
false
) may disable certain advanced features like “Ask AI.”
N8N_DIAGNOSTICS_CONFIG_FRONTEND
/ N8N_DIAGNOSTICS_CONFIG_BACKEND
- Purpose: Specify the front-end and back-end telemetry configs.
- Default: Usually includes the telemetry URLs (e.g.,
https://telemetry.n8n.io
).
2. Database Settings
n8n supports both SQLite (default) and PostgreSQL for data storage. The choice often depends on whether you need a lightweight or production-grade environment.
DB_TYPE
- Purpose: Declares which database type to use:
sqlite
orpostgresdb
. - Default:
sqlite
- Tip: For larger workloads or multi-instance deployments, PostgreSQL is more robust.
DB_TABLE_PREFIX
- Purpose: Optionally add a prefix to all n8n table names.
- Use Case: Helpful if you share a database schema with multiple apps or want to avoid naming conflicts.
PostgreSQL-Specific Variables
DB_POSTGRESDB_DATABASE
: PostgreSQL database name (defaultn8n
).DB_POSTGRESDB_HOST
: Hostname (defaultlocalhost
).DB_POSTGRESDB_PORT
: Port (default5432
).DB_POSTGRESDB_USER
: Database user (defaultpostgres
).DB_POSTGRESDB_PASSWORD
: Password for that user.DB_POSTGRESDB_SCHEMA
: Schema (defaultpublic
).DB_POSTGRESDB_SSL_CA
/DB_POSTGRESDB_SSL_CERT
/DB_POSTGRESDB_SSL_KEY
: Paths to SSL credentials if using secure connections.DB_POSTGRESDB_SSL_REJECT_UNAUTHORIZED
: Whether to reject unauthorized certificates (true
/false
). Default:true
.
3. Execution Settings
Execution settings determine how workflows are run, their timeouts, and how results are persisted.
EXECUTIONS_TIMEOUT
- Purpose: The default maximum execution time, in seconds, before workflows are automatically terminated.
- Why It’s Important: Prevents workflows from running indefinitely and consuming excessive resources. Can be overridden per workflow if needed.
EXECUTIONS_PROCESS
- Purpose: Defines how workflows are processed:
main
: Executions occur in the main process (simpler but less isolated).own
: Each execution spins up its own subprocess (more memory overhead, but better isolation).
EXECUTIONS_MODE
- Purpose: Controls when and how executions are stored.
regular
: The default mode, storing executions based on workflow-specific settings.queue
: Uses a queue-based approach, where workflows line up for sequential processing.
EXECUTIONS_DATA_PRUNE
- Purpose: Automatically deletes execution data older than a certain number of hours.
- Default: Not set (disabled).
- Tip: Useful for managing disk usage and preventing your database or storage from growing indefinitely.
4. Queue and Scaling Settings
For advanced setups that need horizontal scaling or distributed workers.
QUEUE_BULL_REDIS_HOST
, QUEUE_BULL_REDIS_PORT
, QUEUE_BULL_REDIS_DB
- Purpose: Configure the Redis connection used by n8n’s Bull queue.
- Why It Matters: Required if you want to distribute or scale out n8n processes across multiple nodes or servers.
5. Security Settings
Security in n8n can be layered, from basic auth to JWT tokens.
N8N_BASIC_AUTH_ACTIVE
- Purpose: Enables basic HTTP authentication for the n8n editor.
- Default:
false
- When to Use: Quick and easy security for small deployments or internal tools.
N8N_BASIC_AUTH_USER
and N8N_BASIC_AUTH_PASSWORD
- Purpose: The username and password for basic authentication.
- Reminder: Use strong, randomly generated passwords when exposing n8n publicly.
N8N_JWT_AUTH_ACTIVE
- Purpose: Enables JWT-based authentication.
- Default:
false
N8N_JWT_AUTH_HEADER
and N8N_JWT_AUTH_HEADER_VALUE_PREFIX
- Purpose: Specify which HTTP header holds the JWT token and what prefix indicates the token (e.g.,
Bearer
). - Default:
- Header:
Authorization
- Prefix:
Bearer
- Header:
6. Logging Settings
Logging is crucial for monitoring, debugging, and auditing.
N8N_LOG_LEVEL
- Purpose: The verbosity level for logs (
error
,warn
,info
,verbose
,debug
). - Default:
info
- Tip: Use lower verbosity in production to reduce noise and resource consumption.
N8N_LOG_OUTPUT
- Purpose: Specifies the output location (e.g.,
console
or a file path). - Default:
console
- Use Case: Direct logs to a logging service or a dedicated file for compliance or advanced analytics.
7. Webhook Settings
Webhooks are a core feature of n8n, allowing external services to trigger workflows.
WEBHOOK_URL
- Purpose: Override the default webhook endpoint domain/path.
- Why It Matters: If you run n8n behind a reverse proxy or custom domain, you may need to set a public-facing URL for inbound requests.
WEBHOOK_TUNNEL_URL
- Purpose: Custom URL for local development, often used with tunneling tools like ngrok.
- When to Use: Essential for testing webhooks on localhost setups or behind NAT/firewalls.
8. Email Settings
If your workflows involve sending email alerts or notifications, configure SMTP.
N8N_EMAIL_MODE
- Purpose: Determines email sending mechanism (e.g.,
smtp
). - Why It Matters: Ensures that n8n can communicate with users or system administrators through email.
N8N_SMTP_HOST
/ N8N_SMTP_PORT
- Purpose: SMTP server hostname and port.
N8N_SMTP_USER
/ N8N_SMTP_PASS
- Purpose: Credentials for authenticating with your SMTP service.
N8N_SMTP_SENDER
- Purpose: The email address used as the “From” field in outgoing notifications.
- Tip: Use a professional or organisational address to improve credibility and deliverability.
Final Thoughts and Best Practices
Choosing the right environment variables can dramatically simplify your n8n workflow automation and ensure a smooth, secure, and scalable setup. Here are a few additional tips:
- Use a Secrets Manager: For sensitive values like passwords and encryption keys, consider storing them in a dedicated vault or secrets manager (e.g., HashiCorp Vault, AWS Secrets Manager).
- Version Control: If you’re using a
.env
file or a config file, maintain it in a secure version control system and restrict access to authorised personnel only. - Regular Backups: Back up your
.n8n
folder, database, and any important environment variables so you can recover quickly in case of failure. - Consistent Environments: Use the same environment variables across development, staging, and production (with only slight tweaks), ensuring consistency and fewer surprises.
- Consult Official Documentation: For detailed usage or advanced options, refer to the official n8n Documentation.
With these configuration variables optimised for your requirements, n8n can become a cornerstone of your automation strategy—making it easier to integrate multiple services and scale workflows as your needs grow.
Contact us if you need to speak to expert n8n consultants;