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. Setting related to processing payments with Saleor App. 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.