Skip to main content

Environment Variables

Saleor follows the 12-factor approach, so you can configure Saleor using environment variables.

Below is a list of available environment variables and their default values.

Setting environment variables

While most production environments offer a way to configure the environment, you will likely want to set them on your local development machine first.

To set the variable temporarily, until the terminal window is closed:

set SECRET_KEY "<mysecretkey>"

To permanently set the variable:

setx SECRET_KEY "<mysecretkey>"

General configuration

ALLOWED_CLIENT_HOSTS

A list of strings representing host/domain names of client applications (storefront or dashboard) that use this Saleor instance as a backend. Values in this list should be URLs in RFC 1808 format.

Some operations, such as registering a new account or resetting the password, involve sending an email from the backend with a link that users need to click to confirm the action. The backend doesn't know the structure of frontend applications' routing, and the path to the view where users can proceed with the operation needs to be passed as arguments in GraphQL mutations. These paths are validated against URLs configured in the ALLOWED_CLIENT_HOSTS setting.

ALLOWED_CLIENT_HOSTS is required in production mode (with DEBUG=False). In local development (DEBUG=True), when it's not set, the paths are validated against localhost, 127.0.0.1.

Multiple values should be separated with a comma.

ALLOWED_GRAPHQL_ORIGINS

Controls the value of Access-Control-Allow-Origin response header. Defaults to *.

ALLOWED_HOSTS

This variable controls Django's allowed hosts setting. It defaults to localhost.

Multiple values should be separated with a comma.

CACHE_URL or REDIS_URL

The URL of a cache database. It defaults to local process memory.

Redis is recommended.

Example: redis://redis.example.com:6379/0

CELERY_BROKER_URL

Default task broker URL. You can read more about configuring this at Celery Documentation.

CHECKOUT_TTL_BEFORE_RELEASING_FUNDS

Defines the TTL of checkout before it is marked as abandoned, and assigned funds will be released. The value should be a time expression like 5m, 5 minutes, 5d, 5 days, 1w, or 1 week. Defaults to 6 hours.

DATABASE_URL

The connection URL to a PostgreSQL database. Defaults to postgres://saleor:saleor@localhost:5432/saleor.

Format: postgres://<username>:<password>@<hostname>:<port>/<database-name>

DEBUG

Controls Django's debug mode. It defaults to True.

DEFAULT_COUNTRY

Indicates the default country of your store. Depending on what setup you require, this variable also controls the default VAT, shipping country, etc. Defaults to US.

DEFAULT_CURRENCY

Indicates a default currency which is a basis for all prices entered and stored in your store. Defaults to USD.

DEFAULT_FROM_EMAIL

Indicates a default email address to use for all outgoing mail.

ENABLE_DEBUG_TOOLBAR

Controls whether to run Django Debug Toolbar. Defaults to False.

To use the toolbar, you must also enable the PLAYGROUND_ENABLED setting. Then, the toolbar will be rendered when accessing the /graphql/ URL. Note that using the toolbar is recommended only locally and should be disabled in production, as it affects the performance and may potentially reveal sensitive or private information.

ENABLE_SSL

Used while generating URLs. Set to True if Saleor is deployed behind HTTPS. Defaults to False.

caution

If the PUBLIC_URL is set, it takes precedence over the ENABLE_SSL setting when generating URLs.

EMAIL_URL

The URL of the email gateway. Defaults to printing everything to the console.

Some examples:

DescriptionURL
Amazon SESsmtp://username:password@email-smtp.us-east-1.amazonaws.com:587/?tls=True
Gmailsmtp://my.gmail.username@gmail.com:my-password@smtp.gmail.com:465/?ssl=True
Mailgunsmtp://username:password@smtp.mailgun.org:465/?ssl=True
Mailjetsmtp://username:password@in-v3.mailjet.com:587/?tls=True
OVHsmtp://username@example.com:my-password@pro1.mail.ovh.net:587/?tls=True
SendGridsmtp://apikey:your.api.key@smtp.sendgrid.com:465/?ssl=True
A SMTP server unencryptedsmtp://username@example.com:my-password@smtp.example.com:25/

Example: smtp://user:password@smtp.example.com:465/?ssl=True

USER_EMAIL_URL

The URL used by UserEmails.

Some examples:

DescriptionURL
Amazon SESsmtp://username:password@email-smtp.us-east-1.amazonaws.com:587/?tls=True
Gmailsmtp://my.gmail.username@gmail.com:my-password@smtp.gmail.com:465/?ssl=True
Mailgunsmtp://username:password@smtp.mailgun.org:465/?ssl=True
Mailjetsmtp://username:password@in-v3.mailjet.com:587/?tls=True
OVHsmtp://username@example.com:my-password@pro1.mail.ovh.net:587/?tls=True
SendGridsmtp://apikey:your.api.key@smtp.sendgrid.com:465/?ssl=True
A SMTP server unencryptedsmtp://username@example.com:my-password@smtp.example.com:25/

Example: smtp://user:password@smtp.example.com:465/?ssl=True

FEDERATED_QUERY_MAX_ENTITIES

Sets upper limit on how many entities may be requested by Apollo Federation's gateway for a single GraphQL query. Defaults to 100. Set to 0 to remove this limit.

GRAPHQL_QUERY_MAX_COMPLEXITY

Controls maximum allowed complexity (cost) of a GraphQL query. If the query's complexity exceeds this limit, it will not be executed, and GraphQL API will return an error instead.

Set 0 to remove this limit.

INTERNAL_IPS

Controls Django's internal IPs setting. Defaults to 127.0.0.1.

Multiple values should be separated with a comma.

HTTP_IP_FILTER_ENABLED

Added in v3.16

A boolean setting that controls whether or not to enable IP filtering in HTTP(S) network calls (webhooks, OIDC, etc.).

When set to True (default) it will reject private and loopback IP address ranges (see also HTTP_IP_FILTER_ALLOW_LOOPBACK_IPS).

It defaults to True, and is recommended to be enabled on environments where staff users are untrusted, and thus could lead to SSRF attacks.

HTTP_IP_FILTER_ALLOW_LOOPBACK_IPS

Added in v3.16

When set to False (default), the HTTP IP filter will reject loopback IP addresses (127.0.0.0 to 127.255.255.255 range).

JWT_TTL_ACCESS

The time until JWT access tokens expire. The value should be a time expression like 5m, 5 minutes, 5d, 5 days, 1w, or 1 week. Defaults to 5 minutes.

JWT_TTL_REFRESH

The time until JWT refresh tokens expire. The value should be a time expression like 5m, 5 minutes, 5d, 5 days, 1w, or 1 week. Defaults to 30 days.

JWT_TTL_REQUEST_EMAIL_CHANGE

The time until email change request tokens expire. The value should be a time expression like 5m, 5 minutes, 5d, 5 days, 1w, or 1 week. Defaults to 1 hour.

RSA_PRIVATE_KEY

The RSA private key in PEM format is used for signing Saleor's JWT tokens. This is unnecessary in the DEBUG mode as Saleor will generate a temporary private key. It is required in production environments.

RSA_PRIVATE_PASSWORD

The password is required for loading RSA_PRIVATE_KEY. Default set to None.

MAX_CHECKOUT_LINE_QUANTITY

Controls the maximum quantity of a line item that can be added to a single checkout. Defaults to 50.

MEDIA_URL

Controls Django's MEDIA_URL setting. Defaults to /media/.

PUBLIC_URL

Specifies the base URL at which Saleor is hosted, such as https://api.example.com/. This setting takes precedence over both ENABLE_SSL and Shop.domain (set using the GraphQL API) when generating URLs. Ensure to provide the complete URL, including the protocol: http:// or https://.

PLAYGROUND_ENABLED

Controls whether to run Playground - the interactive GraphQL explorer - when accessing the /graphql/ URL exposed by Saleor. Defaults to True.

SECRET_KEY

Controls Django's secret key setting.

STATIC_URL

Controls the production assets mount path. Defaults to /static/.

Currency exchange

Saleor can automatically convert amounts between currencies. To use this feature, you will need an Open Exchange Rates account.

OPENEXCHANGERATES_API_KEY

Your store's Open Exchange Rates "App ID".

Updating domain configuration

When deploying Saleor under a specific domain, such as api.example.com, it's essential to ensure that Saleor is properly configured to generate URLs. This can be achieved using the PUBLIC_URL environment variable. Once configured, Saleor will effectively generate URLs tailored to its domain, ensuring smooth bidirectional communication.