Configuration Options ​

Environment variables are used for all configuration within a Directus project. These variables can be defined in a number of ways, which we cover below.

Configuration Files ​

By default, Directus will read the .env file located next to your project's package.json (typically in the root folder of your project) for its configuration. You can change this path and filename by setting the CONFIG_PATH environment variable before starting Directus. For example:

CONFIG_PATH="/path/to/config.js" npx directus start

CONFIG_PATH="/path/to/config.js" npx directus start

In case you prefer using a configuration file instead of environment variables, you can also use the CONFIG_PATH environment variable to instruct Directus to use a local configuration file instead of environment variables. The config file can be one of the following formats:

• .env
• config.json
• config.yaml
• config.js

.env ​

If the config path has no file extension, or a file extension that's not one of the other supported formats, Directus will try reading the file config path as environment variables. This has the following structure:

HOST="0.0.0.0"
PORT=8055

DB_CLIENT="pg"
DB_HOST="localhost"
DB_PORT=5432

etc

HOST="0.0.0.0"
PORT=8055

DB_CLIENT="pg"
DB_HOST="localhost"
DB_PORT=5432

etc

config.json ​

If you prefer a single JSON file for your configuration, create a JSON file with the environment variables as keys, for example:

CONFIG_PATH="/path/to/config.json"

CONFIG_PATH="/path/to/config.json"

{
	"HOST": "0.0.0.0",
	"PORT": 8055,

	"DB_CLIENT": "pg",
	"DB_HOST": "localhost",
	"DB_PORT": 5432

	// etc
}

{
	"HOST": "0.0.0.0",
	"PORT": 8055,

	"DB_CLIENT": "pg",
	"DB_HOST": "localhost",
	"DB_PORT": 5432

	// etc
}

config.yaml ​

Similar to JSON, you can use a .yaml (or .yml) file for your config:

CONFIG_PATH="/path/to/config.yaml"

CONFIG_PATH="/path/to/config.yaml"

HOST: 0.0.0.0
PORT: 8055

DB_CLIENT: pg
DB_HOST: localhost
DB_PORT: 5432
#
# etc

HOST: 0.0.0.0
PORT: 8055

DB_CLIENT: pg
DB_HOST: localhost
DB_PORT: 5432
#
# etc

config.js ​

Using a JavaScript file for your config allows you to dynamically generate the configuration of the project during startup.

By default, the file is expected to be a ESM, while CommonJS is supported too by using .cjs as the file extension.

The JavaScript configuration supports two different formats, either an Object Structure where the key is the environment variable name:

export default {
	HOST: '0.0.0.0',
	PORT: 8055,

	DB_CLIENT: 'pg',
	DB_HOST: 'localhost',
	DB_PORT: 5432,

	// etc
};

export default {
	HOST: '0.0.0.0',
	PORT: 8055,

	DB_CLIENT: 'pg',
	DB_HOST: 'localhost',
	DB_PORT: 5432,

	// etc
};

module.exports = {
	HOST: '0.0.0.0',
	PORT: 8055,

	DB_CLIENT: 'pg',
	DB_HOST: 'localhost',
	DB_PORT: 5432,

	// etc
};

module.exports = {
	HOST: '0.0.0.0',
	PORT: 8055,

	DB_CLIENT: 'pg',
	DB_HOST: 'localhost',
	DB_PORT: 5432,

	// etc
};

Or a Function Structure that returns the same object format as above. The function gets process.env as its parameter.

export default function (env) {
	return {
		HOST: '0.0.0.0',
		PORT: 8055,

		DB_CLIENT: 'pg',
		DB_HOST: 'localhost',
		DB_PORT: 5432,

		// etc
	};
}

export default function (env) {
	return {
		HOST: '0.0.0.0',
		PORT: 8055,

		DB_CLIENT: 'pg',
		DB_HOST: 'localhost',
		DB_PORT: 5432,

		// etc
	};
}

module.exports = function (env) {
	return {
		HOST: '0.0.0.0',
		PORT: 8055,

		DB_CLIENT: 'pg',
		DB_HOST: 'localhost',
		DB_PORT: 5432,

		// etc
	};
};

module.exports = function (env) {
	return {
		HOST: '0.0.0.0',
		PORT: 8055,

		DB_CLIENT: 'pg',
		DB_HOST: 'localhost',
		DB_PORT: 5432,

		// etc
	};
};

Environment Variable Files ​

Any of the environment variable values can be imported from a file, by appending _FILE to the environment variable name. This is especially useful when used in conjunction with Docker Secrets, so you can keep sensitive data out of your compose files. For example:

DB_PASSWORD_FILE="/run/secrets/db_password"

DB_PASSWORD_FILE="/run/secrets/db_password"

Type Casting and Nesting ​

Environment variables are automatically type cast based on the structure of the variable, for example:

PUBLIC_URL="https://example.com"
// "https://example.com"

DB_HOST="3306"
// 3306

CORS_ENABLED="false"
// false

STORAGE_LOCATIONS="s3,local,example"
// ["s3", "local", "example"]

PUBLIC_URL="https://example.com"
// "https://example.com"

DB_HOST="3306"
// 3306

CORS_ENABLED="false"
// false

STORAGE_LOCATIONS="s3,local,example"
// ["s3", "local", "example"]

In cases where the environment variables are converted to a configuration object for third party library use, like in DB_* or REDIS_*, the environment variable will be converted to camelCase. You can use a double underscore (__) for nested objects:

DB_CLIENT="pg"
DB_CONNECTION_STRING="postgresql://postgres:example@127.0.0.1"
DB_SSL__REJECT_UNAUTHORIZED="false"

{
	client: "pg",
	connectionString: "postgresql://postgres:example@127.0.0.1",
	ssl: {
		rejectUnauthorized: false
	}
}

DB_CLIENT="pg"
DB_CONNECTION_STRING="postgresql://postgres:example@127.0.0.1"
DB_SSL__REJECT_UNAUTHORIZED="false"

{
	client: "pg",
	connectionString: "postgresql://postgres:example@127.0.0.1",
	ssl: {
		rejectUnauthorized: false
	}
}

Environment Syntax Prefix ​

Directus will attempt to automatically type cast environment variables based on context clues. If you have a specific need for a given type, you can tell Directus what type to use for the given value by prefixing the value with {type}:. The following types are available:

Explicit casting is also available when reading from a file with the _FILE suffix.

General ​

^[1] The PUBLIC_URL value is used for things like OAuth redirects, forgot-password emails, and logos that needs to be publicly available on the internet.

Server ​

Database ​

Redis ​

Directus requires Redis for multi-container deployments. This ensures that things like caching, rate-limiting, and WebSockets work reliably across multiple containers of Directus.

Redis is required when you run Directus load balanced across multiple containers/processes.

Data Retention ​

Security ​

^[1] When SECRET is not set, a random value will be used. This means sessions won't persist across system restarts or horizontally scaled deployments. Must be explicitly set to a secure random value in production.

^[2] localhost can get resolved to ::1 as well as 127.0.0.1 depending on the system - ensure to include both if you want to specifically block localhost.

Hashing ​

Argon2's hashing function is used by Directus for three purposes: 1) hashing user passwords, 2) generating hashes for the Hash field type in collections, and 3) the generate a hash API endpoint.

All HASH_* environment variable parameters are passed to the argon2.hash function. See the node-argon2 library options page for reference.

CORS ​

Rate Limiting ​

You can use the built-in rate-limiter to prevent users from hitting the API too much. Simply enabling the rate-limiter will set a default maximum of 50 requests per second, tracked in memory.

Based on the RATE_LIMITER_STORE used, you must also provide the following configurations:

Example: Basic ​

# 10 requests per 5 seconds
RATE_LIMITER_POINTS="10"
RATE_LIMITER_DURATION="5"

# globally 100 requests per 5 seconds
RATE_LIMITER_GLOBAL_POINTS="100"
RATE_LIMITER_GLOBAL_DURATION="5"

# 10 requests per 5 seconds
RATE_LIMITER_POINTS="10"
RATE_LIMITER_DURATION="5"

# globally 100 requests per 5 seconds
RATE_LIMITER_GLOBAL_POINTS="100"
RATE_LIMITER_GLOBAL_DURATION="5"

Pressure-based rate limiter ​

This rate-limiter prevents the API from accepting new requests while the server is experiencing high load. This continuously monitors the current event loop and memory usage, and error out requests with a 503 early when the system is overloaded.

Cache ​

Directus has a built-in data-caching option. Enabling this will cache the output of requests (based on the current user and exact query parameters used) into configured cache storage location. This drastically improves API performance, as subsequent requests are served straight from this cache. Enabling cache will also make Directus return accurate cache-control headers. Depending on your setup, this will further improve performance by caching the request in middleman servers (like CDNs) and even the browser.

^[1] CACHE_TTL Based on your project's needs, you might be able to aggressively cache your data, only requiring new data to be fetched every hour or so. This allows you to squeeze the most performance out of your Directus instance. This can be incredibly useful for applications where you have a lot of (public) read-access and where updates aren't real-time (for example a website). CACHE_TTL uses ms to parse the value, so you configure it using human readable values (like 2 days, 7 hrs, 5m).

^[2] CACHE_AUTO_PURGE allows you to keep the Directus API real-time, while still getting the performance benefits on quick subsequent reads.

^[3] The cache has to be manually cleared when requiring to access updated results for collections in CACHE_AUTO_PURGE_IGNORE_LIST.

^[4] Not affected by the CACHE_ENABLED value.

^[5] CACHE_STORE For larger projects, you most likely don't want to rely on local memory for caching. Instead, you can use the above CACHE_STORE environment variable to use redis as the cache store.

File Storage ​

By default, Directus stores all uploaded files locally on disk. However, you can also configure Directus to use S3, Google Cloud Storage, Azure, Cloudinary or Supabase. You can also configure multiple storage adapters at the same time. This allows you to choose where files are being uploaded on a file-by-file basis. In the Data Studio, files will automatically be uploaded to the first configured storage location (in this case local). The used storage location is saved under storage in directus_files.

STORAGE_LOCATIONS="local"
STORAGE_LOCAL_ROOT="./uploads"

STORAGE_LOCATIONS="local"
STORAGE_LOCAL_ROOT="./uploads"

STORAGE_LOCATIONS="s3"
STORAGE_s3_DRIVER="s3" # Will not work, lowercase "s3" ❌

STORAGE_LOCATIONS="s3"
STORAGE_s3_DRIVER="s3" # Will not work, lowercase "s3" ❌

STORAGE_LOCATIONS="s3"
STORAGE_S3_DRIVER="s3" # Will work, "s3" is uppercased ✅

STORAGE_LOCATIONS="s3"
STORAGE_S3_DRIVER="s3" # Will work, "s3" is uppercased ✅

For each of the storage locations listed, you must provide the following configuration:

Based on your configured driver, you must also provide the following configurations:

Local (local) ​

S3 (s3) ​

^[1] When overriding this variable for S3, make sure to add your bucket's region in the endpoint: s3.{region}.amazonaws.com.

Azure (azure) ​

Google Cloud Storage (gcs) ​

Cloudinary (cloudinary) ​

Supabase (supabase) ​

Example: Multiple Storage Adapters ​

Below showcases a CSV of storage location names, with a config block for each:

STORAGE_LOCATIONS="local,aws"

STORAGE_LOCAL_DRIVER="local"
STORAGE_LOCAL_ROOT="local"

STORAGE_AWS_KEY="tp15c...510vk"
STORAGE_AWS_SECRET="yk29b...b932n"
STORAGE_AWS_REGION="us-east-2"
STORAGE_AWS_BUCKET="my-files"

STORAGE_LOCATIONS="local,aws"

STORAGE_LOCAL_DRIVER="local"
STORAGE_LOCAL_ROOT="local"

STORAGE_AWS_KEY="tp15c...510vk"
STORAGE_AWS_SECRET="yk29b...b932n"
STORAGE_AWS_REGION="us-east-2"
STORAGE_AWS_BUCKET="my-files"

Metadata ​

When uploading an image, Directus persists the description, title, and tags from available Exif metadata. For security purposes, collection of additional metadata must be configured:

^[1]: Extracting all metadata might cause memory issues when the file has an unusually large set of metadata

Upload Limits ​

Chunked Uploads ​

Large files can be uploaded in chunks to improve reliability and efficiency, especially in scenarios with network instability or limited bandwidth. This is implemented using the TUS protocol.

Assets ​

Image transformations can be fairly heavy on memory usage. If you're using a system with 1GB or less available memory, we recommend lowering the allowed concurrent transformations to prevent you from overflowing your server.

[^1]: The maximum value is the square root of Node's Number.MAX_SAFE_INTEGER, or 95,906,265 at time of writing. Be advised: transforming gigantic files can hurt your server performance and cause outages.

Authentication ​

For each auth provider you list, you must also provide the following configuration:

You may also be required to specify additional variables depending on the auth driver. See configuration details below.

Local (local) ​

The default Directus email/password authentication flow.

No additional configuration required.

SSO (oauth2 and openid) ​

Directus' SSO integrations provide powerful alternative ways to authenticate into your project. Directus will ask you to login on the external service, and return authenticated with a Directus account linked to that service.

For example, you can login to Directus using a GitHub account by creating an OAuth 2.0 app in GitHub and adding the following configuration to Directus:

AUTH_PROVIDERS="github"

AUTH_GITHUB_DRIVER="oauth2"
AUTH_GITHUB_CLIENT_ID="99d3...c3c4"
AUTH_GITHUB_CLIENT_SECRET="34ae...f963"
AUTH_GITHUB_AUTHORIZE_URL="https://github.com/login/oauth/authorize"
AUTH_GITHUB_ACCESS_URL="https://github.com/login/oauth/access_token"
AUTH_GITHUB_PROFILE_URL="https://api.github.com/user"
AUTH_GITHUB_ALLOW_PUBLIC_REGISTRATION=true

AUTH_PROVIDERS="github"

AUTH_GITHUB_DRIVER="oauth2"
AUTH_GITHUB_CLIENT_ID="99d3...c3c4"
AUTH_GITHUB_CLIENT_SECRET="34ae...f963"
AUTH_GITHUB_AUTHORIZE_URL="https://github.com/login/oauth/authorize"
AUTH_GITHUB_ACCESS_URL="https://github.com/login/oauth/access_token"
AUTH_GITHUB_PROFILE_URL="https://api.github.com/user"
AUTH_GITHUB_ALLOW_PUBLIC_REGISTRATION=true

More example SSO configurations can be found here.

OAuth 2.0 ​

^[1] When authenticating, Directus will match the identifier value from the external user profile to a Directus users "External Identifier".

OpenID ​

OpenID is an authentication protocol built on OAuth 2.0, and should be preferred over standard OAuth 2.0 where possible.

^[1] When authenticating, Directus will match the identifier value from the external user profile to a Directus users "External Identifier".

^[2] sub represents a unique user identifier defined by the OpenID provider. For users not relying on PUBLIC_REGISTRATION it is recommended to use a human-readable identifier, such as email.

^[3] As directus only allows one role per user, evaluating stops after the first match. An OpenID user that is member of both e.g. developer and admin groups may be assigned different roles depending on the order that you specify your role-mapping in: In the following example said OpenID user will be assigned the role directus_developer_role_id

AUTH_<PROVIDER>_ROLE_MAPPING: json:{ "developer": "directus_developer_role_id", "admin": "directus_admin_role_id" }"

AUTH_<PROVIDER>_ROLE_MAPPING: json:{ "developer": "directus_developer_role_id", "admin": "directus_admin_role_id" }"

Whereas in the following example the OpenID user will be assigned the role directus_admin_role_id

AUTH_<PROVIDER>_ROLE_MAPPING: json:{ "admin": "directus_admin_role_id", "developer": "directus_developer_role_id" }"

AUTH_<PROVIDER>_ROLE_MAPPING: json:{ "admin": "directus_admin_role_id", "developer": "directus_developer_role_id" }"

LDAP (ldap) ​

LDAP allows Active Directory users to authenticate and use Directus without having to be manually configured. User information and roles will be assigned from Active Directory.

^[1] The bind user must have permission to query users and groups to perform authentication. Anonymous binding can by achieved by setting an empty value for BIND_DN and BIND_PASSWORD.

^[2] The scope defines the following behaviors:

• base: Limits the scope to a single object defined by the associated DN.
• one: Searches all objects within the associated DN.
• sub: Searches all objects and sub-objects within the associated DN.

^[3] If GROUP_DN is specified, the user's role will always be updated on authentication to a matching group configured in AD, or fallback to the DEFAULT_ROLE_ID.

Example: LDAP ​

AUTH_PROVIDERS="ldap"

AUTH_LDAP_DRIVER="ldap"
AUTH_LDAP_CLIENT_URL="ldap://ldap.directus.io"
AUTH_LDAP_BIND_DN="CN=Bind User,OU=Users,DC=ldap,DC=directus,DC=io"
AUTH_LDAP_BIND_PASSWORD="p455w0rd"
AUTH_LDAP_USER_DN="OU=Users,DC=ldap,DC=directus,DC=io"
AUTH_LDAP_GROUP_DN="OU=Groups,DC=ldap,DC=directus,DC=io"

AUTH_PROVIDERS="ldap"

AUTH_LDAP_DRIVER="ldap"
AUTH_LDAP_CLIENT_URL="ldap://ldap.directus.io"
AUTH_LDAP_BIND_DN="CN=Bind User,OU=Users,DC=ldap,DC=directus,DC=io"
AUTH_LDAP_BIND_PASSWORD="p455w0rd"
AUTH_LDAP_USER_DN="OU=Users,DC=ldap,DC=directus,DC=io"
AUTH_LDAP_GROUP_DN="OU=Groups,DC=ldap,DC=directus,DC=io"

SAML ​

SAML is an open-standard, XML-based authentication framework for authentication and authorization between two entities without a password.

• Service provider (SP) agrees to trust the identity provider to authenticate users.

• Identity provider (IdP) authenticates users and provides to service providers an authentication assertion that indicates a user has been authenticated.

^[1] When authenticating, Directus will match the identifier value from the external user profile to a Directus users "External Identifier".

The SP_metadata and IDP_metadata variables should be set to the XML metadata provided by the service provider and identity provider respectively.

Example: Multiple Auth Providers ​

You can configure multiple providers for handling authentication in Directus. This allows for different options when logging in. To do this, provide a comma-separated list of provider names, and a config block for each provider:

AUTH_PROVIDERS="google,facebook"

AUTH_GOOGLE_DRIVER="openid"
AUTH_GOOGLE_CLIENT_ID="830d...29sd"
AUTH_GOOGLE_CLIENT_SECRET="la23...4k2l"
AUTH_GOOGLE_ISSUER_URL="https://accounts.google.com/.well-known/openid-configuration"
AUTH_GOOGLE_IDENTIFIER_KEY="email"
AUTH_GOOGLE_ICON="google"
AUTH_GOOGLE_LABEL="Google"

AUTH_FACEBOOK_DRIVER="oauth2"
AUTH_FACEBOOK_CLIENT_ID="830d...29sd"
AUTH_FACEBOOK_CLIENT_SECRET="jd8x...685z"
AUTH_FACEBOOK_AUTHORIZE_URL="https://www.facebook.com/dialog/oauth"
AUTH_FACEBOOK_ACCESS_URL="https://graph.facebook.com/oauth/access_token"
AUTH_FACEBOOK_PROFILE_URL="https://graph.facebook.com/me?fields=email"
AUTH_FACEBOOK_ICON="facebook"
AUTH_FACEBOOK_LABEL="Facebook"

AUTH_PROVIDERS="google,facebook"

AUTH_GOOGLE_DRIVER="openid"
AUTH_GOOGLE_CLIENT_ID="830d...29sd"
AUTH_GOOGLE_CLIENT_SECRET="la23...4k2l"
AUTH_GOOGLE_ISSUER_URL="https://accounts.google.com/.well-known/openid-configuration"
AUTH_GOOGLE_IDENTIFIER_KEY="email"
AUTH_GOOGLE_ICON="google"
AUTH_GOOGLE_LABEL="Google"

AUTH_FACEBOOK_DRIVER="oauth2"
AUTH_FACEBOOK_CLIENT_ID="830d...29sd"
AUTH_FACEBOOK_CLIENT_SECRET="jd8x...685z"
AUTH_FACEBOOK_AUTHORIZE_URL="https://www.facebook.com/dialog/oauth"
AUTH_FACEBOOK_ACCESS_URL="https://graph.facebook.com/oauth/access_token"
AUTH_FACEBOOK_PROFILE_URL="https://graph.facebook.com/me?fields=email"
AUTH_FACEBOOK_ICON="facebook"
AUTH_FACEBOOK_LABEL="Facebook"

Flows ​

const publicUrl = data['$env']['PUBLIC_URL'];
// OR
const publicUrl = data.$env.PUBLIC_URL;
// OR
const publicUrl = process.env.PUBLIC_URL;

const publicUrl = data['$env']['PUBLIC_URL'];
// OR
const publicUrl = data.$env.PUBLIC_URL;
// OR
const publicUrl = process.env.PUBLIC_URL;

Extensions ​

^[1] If EXTENSIONS_LOCATION is configured, this is the path to the extensions folder within the selected storage location.

^[2] EXTENSIONS_AUTO_RELOAD will not work when the EXTENSION_LOCATION environment variable is set.

^[3] The EXTENSIONS_CACHE_TTL environment variable controls for how long custom app extensions (e.t., interface, display, layout, module, panel) are cached by browsers. Caching can speed-up the loading of the app as the code for the extensions doesn't need to be re-fetched from the server on each app reload. On the other hand, this means that code changes to app extensions won't be taken into account by the browser until EXTENSIONS_CACHE_TTL has expired. By default, extensions are not cached. The input data type for this environment variable is the same as CACHE_TTL.

^[4] By default extensions are loaded from the local file system. EXTENSIONS_LOCATION can be used to load extensions from a storage location instead. Under the hood, they are synced into a local directory within TEMP_PATH and then loaded from there.

Marketplace ​

Synchronization ​

Email ​

Based on the EMAIL_TRANSPORT used, you must also provide the following configurations:

Sendmail (sendmail) ​

SMTP (smtp) ​

For more details about these options, see the SMTP configuration documentation for Nodemailer, which Directus uses under the hood.

Mailgun (mailgun) ​

AWS SES (ses) ​

Admin Account ​

If you're relying on Docker and/or the directus bootstrap CLI command, you can pass the following two environment variables to automatically configure the first user:

Telemetry ​

To more accurately gauge the frequency of installation, version fragmentation, and general size of the user base, Directus collects little and anonymized data about your environment.

Limits & Optimizations ​

Allows you to configure hard technical limits, to prevent abuse and optimize for your particular server environment.

WebSockets ​

^[1] It's recommended to keep this value between 30 and 120 seconds, otherwise the connections could be considered idle by other parties and therefore terminated. See https://websockets.readthedocs.io/en/stable/topics/timeouts.html.

REST ​

GraphQL ​

Logs ​

The WebSocket Logs endpoint is accessible at /websocket/logs. The method of authentication is limited to strict and the connection will be disconnected when the authentication expires. Refer to the authentication guide for more information.

PM2 ​

For more information on what these options do, please refer to the pm2 documentation.

^[1] Redis is required in case of multiple instances.