directus/docs/reference/environment-variables.md

Environment Variables

Environment variables are used for all configuration within Directus projects. They can either be defined as plain environment variables or via the .env file in the root directory, which is created during the installation process.

toc

General

Variable	Description	Default Value
CONFIG_PATH	Where your config file is located. See Config Files	.env
PORT	What port to run the API under.	8055
PUBLIC_URL[1]	URL where your API can be reached on the web.	/
LOG_LEVEL	What level of detail to log. One of fatal, error, warn, info, debug, trace or silent.	info
LOG_STYLE	Render the logs human readable (pretty) or as JSON. One of pretty, raw.	pretty
MAX_PAYLOAD_SIZE	Controls the maximum request body size. Accepts number of bytes, or human readable string.	100kb
ROOT_REDIRECT	Where to redirect to when navigating to /. Accepts a relative path, absolute URL, or false to disable.	./admin
SERVE_APP	Whether or not to serve the Admin App under /admin.	true

^[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.

Database

Variable	Description	Default Value
DB_CLIENT	Required. What database client to use. One of pg or postgres, mysql, oracledb, mssql, or sqlite3.	--
DB_HOST	Database host. Required when using pg, mysql, oracledb, or mssql.	--
DB_PORT	Database port. Required when using pg, mysql, oracledb, or mssql.	--
DB_DATABASE	Database name. Required when using pg, mysql, oracledb, or mssql.	--
DB_USER	Database user. Required when using pg, mysql, oracledb, or mssql.	--
DB_PASSWORD	Database user's password. Required when using pg, mysql, oracledb, or mssql.	--
DB_FILENAME	Where to read/write the SQLite database. Required when using sqlite3.	--
DB_CONNECTION_STRING	When using pg, you can submit a connection string instead of individual properties. Using this will ignore any of the other connection settings.	--
DB_POOL_*	Pooling settings. Passed on to the tarn.js library.	--

::: tip Additional Database Variables

All DB_* environment variables are passed to the connection configuration of a Knex instance. Based on your project's needs, you can extend the DB_* environment variables with any config you need to pass to the database instance.

:::

::: tip Pooling

All the DB_POOL_ prefixed options are passed to tarn.js through Knex

:::

Security

Variable	Description	Default Value
KEY	Unique identifier for the project.	--
SECRET	Secret string for the project.	--
ACCESS_TOKEN_TTL	The duration that the access token is valid.	15m
REFRESH_TOKEN_TTL	The duration that the refresh token is valid, and also how long users stay logged-in to the App.	7d
REFRESH_TOKEN_COOKIE_DOMAIN	Which domain to use for the refresh cookie. Useful for development mode.	--
REFRESH_TOKEN_COOKIE_SECURE	Whether or not to use a secure cookie for the refresh token in cookie mode.	false
REFRESH_TOKEN_COOKIE_SAME_SITE	Value for sameSite in the refresh token cookie when in cookie mode.	lax
REFRESH_TOKEN_COOKIE_NAME	Name of refresh token cookie .	directus_refresh_token
PASSWORD_RESET_URL_ALLOW_LIST	List of URLs that can be used as reset_url in /password/request	--
USER_INVITE_URL_ALLOW_LIST	List of URLs that can be used as invite_url in /users/invite	--

::: tip Cookie Strictness

Browser are pretty strict when it comes to third-party cookies. If you're running into unexpected problems when running your project and API on different domains, make sure to verify your configuration for REFRESH_TOKEN_COOKIE_NAME, REFRESH_TOKEN_COOKIE_SECURE and REFRESH_TOKEN_COOKIE_SAME_SITE.

:::

CORS

Variable	Description	Default Value
CORS_ENABLED	Whether or not to enable the CORS headers.	true
CORS_ORIGIN	Value for the Access-Control-Allow-Origin header. Use true to match the Origin header, or provide a domain or a CSV of domains for specific access	true
CORS_METHODS	Value for the Access-Control-Allow-Methods header.	GET,POST,PATCH,DELETE
CORS_ALLOWED_HEADERS	Value for the Access-Control-Allow-Headers header.	Content-Type,Authorization
CORS_EXPOSED_HEADERS	Value for the Access-Control-Expose-Headers header.	Content-Range
CORS_CREDENTIALS	Whether or not to send the Access-Control-Allow-Credentials header.	true
CORS_MAX_AGE	Value for the Access-Control-Max-Age header.	18000

Rate Limiting

Variable	Description	Default Value
RATE_LIMITER_ENABLED	Whether or not to enable rate limiting on the API.	false
RATE_LIMITER_POINTS	The amount of allowed hits per duration.	50
RATE_LIMITER_DURATION	The time window in seconds in which the points are counted.	1
RATE_LIMITER_STORE	Where to store the rate limiter counts. One of memory, redis, or memcache.	memory

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

Memory

No additional configuration required.

Redis

Variable	Description	Default Value
RATE_LIMITER_REDIS	Redis connection string, eg: redis://:authpassword@127.0.0.1:6380/4	---

Alternatively, you can provide the individual connection parameters:

Variable	Description	Default Value
RATE_LIMITER_REDIS_HOST	Hostname of the Redis instance	--
RATE_LIMITER_REDIS_PORT	Port of the Redis instance	--
RATE_LIMITER_REDIS_PASSWORD	Password for your Redis instance	--

Memcache

Variable	Description	Default Value
RATE_LIMITER_MEMCACHE	Location of your memcache instance	---

::: tip Additional Rate Limiter Variables

All RATE_LIMITER_* variables are passed directly to a rate-limiter-flexible instance. Depending on your project's needs, you can extend the above environment variables to configure any of the rate-limiter-flexible options.

:::

Cache

Variable	Description	Default Value
CACHE_ENABLED	Whether or not caching is enabled.	false
CACHE_TTL	How long the cache is persisted.	30m
CACHE_CONTROL_S_MAXAGE	Whether to not to add the s-maxage expiration flag. Set to a number for a custom value	0
CACHE_AUTO_PURGE	Automatically purge the cache on create/update/delete actions.	false
CACHE_SCHEMA [1]	Whether or not the database schema is cached. One of false, true, or a string time value	true
CACHE_NAMESPACE	How to scope the cache data.	directus-cache
CACHE_STORE	Where to store the cache data. Either memory, redis, or memcache.	memory

^[1] CACHE_SCHEMA ignores the CACHE_ENABLED value

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

Memory

No additional configuration required.

Redis

Variable	Description	Default Value
CACHE_REDIS	Redis connection string, eg: redis://:authpassword@127.0.0.1:6380/4	---

Alternatively, you can provide the individual connection parameters:

Variable	Description	Default Value
CACHE_REDIS_HOST	Hostname of the Redis instance	--
CACHE_REDIS_PORT	Port of the Redis instance	--
CACHE_REDIS_PASSWORD	Password for your Redis instance	--

Memcache

Variable	Description	Default Value
CACHE_MEMCACHE	Location of your memcache instance	---

Sessions

Sessions are only used in the oAuth authentication flow.

Variable	Description	Default Value
SESSION_STORE	Where to store the session data. Either memory, redis, memcache or database.	memory

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

Memory

No additional configuration required.

Redis

Variable	Description	Default Value
SESSION_REDIS	Redis connection string, eg: redis://:authpassword@127.0.0.1:6380/4	---

Alternatively, you can provide the individual connection parameters:

Variable	Description	Default Value
SESSION_REDIS_HOST	Hostname of the Redis instance	--
SESSION_REDIS_PORT	Port of the Redis instance	--
SESSION_REDIS_PASSWORD	Password for your Redis instance	--

Memcache

Variable	Description	Default Value
SESSION_MEMCACHE_HOSTS	Location of your memcache instance	---

Database

No additional configuration required.

File Storage

Variable	Description	Default Value
STORAGE_LOCATIONS	A CSV of storage locations (eg: local,digitalocean,amazon) to use. You can use any names you'd like for these keys.	local

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

Variable	Description	Default Value
STORAGE_<LOCATION>_DRIVER	Which driver to use, either local, s3, gcs, azure
STORAGE_<LOCATION>_ROOT	Where to store the files on disk	''

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

Local (local)

Variable	Description	Default Value
STORAGE_<LOCATION>_ROOT	Where to store the files on disk	--

S3 (s3)

Variable	Description	Default Value
STORAGE_<LOCATION>_KEY	User key	--
STORAGE_<LOCATION>_SECRET	User secret	--
STORAGE_<LOCATION>_BUCKET	S3 Bucket	--
STORAGE_<LOCATION>_REGION	S3 Region	--
STORAGE_<LOCATION>_ENDPOINT	S3 Endpoint	"s3.amazonaws.com"
STORAGE_<LOCATION>_ACL	S3 ACL	--

Azure (azure)

Variable	Description	Default Value
STORAGE_<LOCATION>_CONTAINER_NAME	Azure Storage container	--
STORAGE_<LOCATION>_ACCOUNT_NAME	Azure Storage account name	--
STORAGE_<LOCATION>_ACCOUNT_KEY	Azure Storage key	--
STORAGE_<LOCATION>_ENDPOINT	Azure URL	"{ACCOUNT_KEY}.blob.core.windows.net"

Google Cloud Storage (gcs)

Variable	Description	Default Value
STORAGE_<LOCATION>_KEY_FILENAME	Path to key file on disk	--
STORAGE_<LOCATION>_BUCKET	Google Cloud Storage bucket	--

If you don't provide any configuration for storage adapters, Directus will default to the following:

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

Assets

Variable	Description	Default Value
ASSETS_CACHE_TTL	How long assets will be cached for in the browser. Sets the max-age value of the Cache-Control header.	30m
ASSETS_TRANSFORM_MAX_CONCURRENT	How many file transformations can be done simultaneously	4
ASSETS_TRANSFORM_IMAGE_MAX_DIMENSION	The max pixel dimensions size (width/height) that is allowed to be transformed	6000
ASSETS_TRANSFORM_MAX_OPERATIONS	The max number of transform operations that is allowed to be processed (excludes saved presets)	5

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.

OAuth

Variable	Description	Default Value
OAUTH_PROVIDERS	CSV of oAuth providers you want to use.	--

For each of the OAuth providers you list, you must also provide a number of extra variables. These differ per external service. The following is a list of common required configuration options:

Variable	Description	Default Value
OAUTH_<PROVIDER>_KEY	oAuth key (a.k.a. application id) for the external service.	--
OAUTH_<PROVIDER>_SECRET	oAuth secret for the external service.	--
OAUTH_<PROVIDER>_SCOPE	A white-space separated list of privileges directus should ask for. A common value is: openid email.	--
OAUTH_<PROVIDER>_AUTHORIZE_URL	The authorize page URL of the external service	--
OAUTH_<PROVIDER>_ACCESS_URL	The access URL of the external service	--
OAUTH_<PROVIDER>_PROFILE_URL	Where Directus can fetch the profile information of the authenticated user.	--

Directus relies on grant for the handling of the oAuth flow. Grant includes a lot of default values for popular services. For example, if you use apple as one of your providers, you only have to specify the key and secret, as Grant has the rest covered. Checkout the grant repo for more information.

Extensions

Variable	Description	Default Value
EXTENSIONS_PATH	Path to your local extensions folder.	./extensions

Email

Variable	Description	Default Value
EMAIL_FROM	Email address from which emails are sent.	no-reply@directus.io
EMAIL_TRANSPORT	What to use to send emails. One of sendmail, smtp, mailgun.	sendmail

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

Sendmail (sendmail)

Variable	Description	Default Value
EMAIL_SENDMAIL_NEW_LINE	What new line style to use in sendmail.	unix
EMAIL_SENDMAIL_PATH	Path to your sendmail executable.	/usr/sbin/sendmail

SMTP (smtp)

Variable	Description	Default Value
EMAIL_SMTP_HOST	SMTP Host	--
EMAIL_SMTP_PORT	SMTP Port	--
EMAIL_SMTP_USER	SMTP User	--
EMAIL_SMTP_PASSWORD	SMTP Password	--
EMAIL_SMTP_POOL	Use SMTP pooling	--
EMAIL_SMTP_SECURE	Enable TLS	--
EMAIL_SMTP_IGNORE_TLS	Ignore TLS	--

Mailgun (mailgun)

Variable	Description	Default Value
EMAIL_MAILGUN_API_KEY	Your Mailgun API key.	--
EMAIL_MAILGUN_DOMAIN	A domain from your Mailgun account	--
EMAIL_MAILGUN_HOST	Allows you to specify a custom host.	'api.mailgun.net'

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:

Variable	Description	Default Value
ADMIN_EMAIL	The email address of the first user that's automatically created when using directus bootstrap.	--
ADMIN_PASSWORD	The password of the first user that's automatically created when using directus bootstrap.	--

Telemetry

To more accurately gauge the frequency of installation, version fragmentation, and general size of the userbase, Directus collects little and anonymized data about your environment. You can easily opt-out with the following environment variable:

Variable	Description	Default Value
TELEMETRY	Allow Directus to collect anonymized data about your environment.	true

---

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"]

In cases where the environment variables are converted to a configuration object for third party library use, like in DB_* or RATE_LIMITER_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
	}
}

Environment Syntax Prefix

Directus will attempt to automatically type cast environment variables based on context clues (see above). 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:

Syntax Prefix	Example	Output
string	string:value	"value"
number	number:3306	3306
regex	regex:/\.example\.com$/	/\.example\.com$/
array	array:https://example.com,https://example2.com	["https://example.com","https://example2.com"]

File Based Environment Variables (Docker Secrets)

Any of the environment variable values can be imported from a file, by appending _FILE to the environment variable name. For example: DB_PASSWORD_FILE="/run/secrets/db_password".

This is especially useful when used in conjunction with Docker Secrets, so you can keep sensitive data out of your compose files.