Environment Variables · Reaction Docs

Reaction Commerce is a system made up of various services and web servers, each of which is distributed as a Docker image, or can be customized and then built into your own Docker image. Container-based microservice deployments typically get much of their configuration from environment variables, and Reaction is no exception. Some environment variables are required because they tell a container service how to connect to another service or a database. Others are optional with sensible defaults, but allow you to customize the system to meet your needs.

This article aims to be a full listing of the required and optional environment variables used by all components of the Reaction Commerce system. If you discover any missing variables, please submit a pull request to update this article.

If you are a developer, check out Developer Concepts: Environment Variables for more information.

For details about how these have changed since the previous release, refer to Upgrading.

API

Variable Name	Description	Local Development	Deployments
`GRAPHQL_INTROSPECTION_ENABLED`	Allow introspection of the GraphQL API.	Because `NODE_ENV` is "development", defaults to `true`. Set to `false` in `.env` to override.	Because `NODE_ENV` is "production", defaults to `false`. Set to `true` to override.
`GRAPHQL_PLAYGROUND_ENABLED`	Serve the GraphQL Playground UI from `/graphql`.	Because `NODE_ENV` is "development", defaults to `true`. Set to `false` in `.env` to override.	Because `NODE_ENV` is "production", defaults to `false`. Set to `true` to override.
`HYDRA_OAUTH2_INTROSPECT_URL`	An OAuth2 URL the API uses to authenticate requests that include an `Authorization` token generated by Hydra.	Defaults to "http://hydra:4445/oauth2/introspect"	Required. You must set this to the internal Hydra Admin hostname plus port, with path `/oauth2/introspect`.
`MAIL_URL`	An SMTP mail url, e.g. `smtp://user:pass@example.com:465`, that is used to send all transactional emails from the `email-smtp` plugin.	No default. Set this in `.env` if you want emails to be sent while you are developing or testing.	Required. Set this or emails will not be sent.
`MONGO_URL`	The MongoDB connection string URL, including the name of the database you want to use.	Defaults to "mongodb://localhost:27017/reaction" in code and to "mongodb://mongo:27017/reaction" in `.env.example`.	Required. There is no default and the service will not start without this set.
`PORT`	Set to any positive integer to run the Express server on a port other than 3000.	Defaults to `3000` in code	Defaults to `3000` in code
`REACTION_ADMIN_PUBLIC_ACCOUNT_REGISTRATION_URL`	The registration URL to be used in new account invitation emails	Because `NODE_ENV` is "development", defaults to `http://localhost:4080`.	Required. There is no default and the service will not start without this set. The value should be the public root URL of your Reaction Admin.
`REACTION_GRAPHQL_SUBSCRIPTIONS_ENABLED`	Enable GraphQL subscriptions over WebSockets	Defaults to `true`. Set to `false` in `.env` to disable.	Defaults to `true`. Set to `false` to disable.
`REACTION_IDENTITY_PUBLIC_PASSWORD_RESET_URL`	The URL of the password reset UI (e.g., `/account/reset-password/TOKEN`) on the Reaction Identity domain, with all-uppercase `TOKEN` as the placeholder for the reset token.	Because `NODE_ENV` is "development", defaults to "http://localhost:4100/account/reset-password/TOKEN".	Required. There is no default and the service will not start without this set.
`REACTION_IDENTITY_PUBLIC_VERIFY_EMAIL_URL`	The URL of the email verification UI (e.g., `/#/verify-email/TOKEN`) on the Reaction Identity domain, with all-uppercase `TOKEN` as the placeholder for the verification token.	Because `NODE_ENV` is "development", defaults to "http://localhost:4100/#/verify-email/TOKEN".	Required. There is no default and the service will not start without this set.
`REACTION_LOG_LEVEL`	The log level, which controls how much is printed in the logs.	Because `NODE_ENV` is "development", defaults to `DEBUG`. Set to another level in `.env` if you want to override.	Because `NODE_ENV` is "production", defaults to `WARN`. Set to another value if you want to override.
`REACTION_SHOULD_INIT_REPLICA_SET`	If this is `true`, on startup the API will auto-initialize a MongoDB replica set if one isn't found.	Because `NODE_ENV` is "development", defaults to `true`. Set to `false` in `.env` if you want to override.	Because `NODE_ENV` is "production", defaults to `false`. Set to `true` if you want to override.
`REACTION_WORKERS_ENABLED`	Set to `false` to disable background job workers. Be careful because at least one instance must be working background jobs or features such as emailing and file uploads won't work.	Defaults to `true`. Set to `false` in `.env` if you want to override.	Defaults to `true`. Set to `false` if you want to override.
`ROOT_URL`	The root URL with protocol for this API, such as `https://shop.mydomain.me`	Because `NODE_ENV` is "development", defaults to "http://localhost:3000".	Required. There is no default and the service will not start without this set.
`STRIPE_API_KEY`	The Stripe secret key from your Stripe account dashboard. Required if you want Stripe payments to work.	Set to a fake value "YOUR_PRIVATE_STRIPE_API_KEY" in `.env.example`. Change to a real `test` API key from Stripe in `.env` if you are developing or testing Stripe payments.	Required if you are processing payments using Stripe. There is no default. If you aren't using Stripe but you have the `payments-stripe` plugin registered, set this to any string.

Hydra

Other environment variables or configuration options may be available. Refer to the Hydra documentation.

Variable Name	Description	Local Development	Deployments
`DSN`	The Postres database connection string	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`OAUTH2_EXPOSE_INTERNAL_ERRORS`	Useful for debugging. Refer to https://www.ory.sh/docs/next/hydra/debugging#first-aid	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Defaults to `false`. Set to `true` as needed in non-production environments only.
`OIDC_SUBJECT_IDENTIFIERS_ENABLED`	Refer to https://www.ory.sh/docs/oryos.9/hydra/advanced#openid-connect	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set. Be careful never to change this in production.
`OIDC_SUBJECT_IDENTIFIERS_PAIRWISE_SALT`	Refer to https://www.ory.sh/docs/oryos.9/hydra/advanced#openid-connect	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set. Be careful never to change this in production.
`SECRETS_SYSTEM`	A key or keys used to encrypt sensitive data using AES-GCM (256 bit) and validate HMAC signatures. Must be at least 16 characters long. This may be a single key or a comma-separated list where the first item in the list is used for signing and encryption and the whole list is used for verifying signatures and decryption. See https://www.ory.sh/docs/hydra/configuration	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set. Be careful never to change this in production.
`SECRETS_COOKIE`	A secret or secrets that are used to encrypt cookie sessions. Defaults to the same keys from `SECRETS_SYSTEM` but Hydra recommends using a separate secret in production. See https://www.ory.sh/docs/hydra/configuration	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Optional, but recommended by Hydra for production
`SERVE_PUBLIC_CORS_ALLOWED_ORIGINS`	Set this to a comma-delimited list of origin URLs that should be allowed to do browser-based login. In particular, set this to the public root URL of your Reaction Admin site, plus any single-page apps you have built to use standard browser-based OIDC authentication flows.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Not required, but logins from Reaction Admin and any other OIDC apps will fail without this set properly.
`SERVE_PUBLIC_CORS_ENABLED`	Set this to `true` to enable browser-based login flows. See also `SERVE_PUBLIC_CORS_ALLOWED_ORIGINS`.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Not required, but logins from Reaction Admin and any other OIDC apps will fail without this set to `true`.
`URLS_CONSENT`	Reaction Identity consent URL (the root URL plus `/consent`).	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and login flows will fail without this set.
`URLS_ERROR`	Reaction Identity errors URL (the root URL plus `/account/oauth-error`).	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Technically optional, but errors will be shown on a less pretty default page if you don't set this.
`URLS_LOGIN`	Reaction Identity login URL (the root URL plus `/login`).	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and login flows will fail without this set.
`URLS_LOGOUT`	Reaction Identity logout URL (the root URL plus `/logout`).	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and logout flows will fail without this set.
`URLS_SELF_ISSUER`	The public URL of Hydra (public OAuth port).	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.

Example Storefront

Variable Name	Description	Local Development	Deployments
`CANONICAL_URL`	The canonical root public URL for your storefront.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`ENABLE_SPA_ROUTING`	By default, the example storefront uses in-browser routing as you click links to move around the site. In other words, the pages are not requested from the NextJS server but rather generated locally. If you need all links to do a full page refresh, then set this to `false`.	Defaults to `true` in code. Set to `false` in `.env` if needed.	Defaults to `true` in code. Set to `false` if you need full page refreshes.
`EXTERNAL_GRAPHQL_URL`	The public Reaction API URL	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`INTERNAL_GRAPHQL_URL`	The internal Reaction API URL	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`NODE_ENV`	Standard Node environment designation	Be sure that `NODE_ENV` is NOT in your `.env` file	For deployed environments (including non-production), be sure to set `NODE_ENV` to `production` or NextJS will run in development mode, which makes pages take a long time to load.
`OAUTH2_ADMIN_PORT`	The internal Hydra admin port	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set. (Set to `4445` unless you have changed it to something else in your Hydra config.)
`OAUTH2_ADMIN_URL`	The internal Hydra admin URL with port	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set. (Set to `http://hydra:4445` unless you have changed the port to something else in your Hydra config.)
`OAUTH2_AUTH_URL`	Hydra's public OAuth "auth" URL, where the path portion is `/oauth2/auth`	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`OAUTH2_CLIENT_ID`	On startup, the storefront service will create or update a Hydra client with this name.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set. Recommend something like "storefront-web", or anything that is unique and descriptive. Keep in mind that if you change this it will effectively log everyone out.
`OAUTH2_CLIENT_SECRET`	On startup, the storefront service will create or update a Hydra client with this client secret.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`OAUTH2_PUBLIC_LOGOUT_URL`	Hydra's public OpenID Connect logout URL, where the path portion is `/oauth2/sessions/logout`.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`OAUTH2_HOST`	The internal Hydra hostname.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`OAUTH2_IDP_PUBLIC_CHANGE_PASSWORD_URL`	The full public URL for the change password page on Reaction Identity. The path portion should be `/account/change-password?email=EMAIL&from=FROM`. Uppercase `EMAIL` and `FROM` placeholders are replaced with the current user's email address and the current page URL.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`OAUTH2_IDP_HOST_URL`	The full internal URL and port for the new Reaction Identity service. Usually something like `http://identity:4100`.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`OAUTH2_TOKEN_URL`	The full internal URL for Hydra's token endpoint. Usually something like `http://hydra:4444/oauth2/token`.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`PORT`	Port on which to run the storefront server in the container.	Defaults to `4000`. Override in `.env` if needed.	Defaults to `4000`
`SEGMENT_ANALYTICS_SKIP_MINIMIZE`	In non-production environments, you may want to set this to `true` to skip minimization of the Segment Analytics code snippet.	Default is `false`. Override in `.env` if needed.	Default is `false`
`SEGMENT_ANALYTICS_WRITE_KEY`	Set this if you want to track storefront analytics such as page views with Segment. You can find this key on your Segment dashboard.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required only if you want to enable Segment analytics
`SESSION_MAX_AGE_MS`	The maximum age in milliseconds for the storefront session cookie, which is used for authentication. Note that Hydra also tracks an authentication session with its own cookie, so setting this lower than the Hydra cookie lifetime will likely result in users being silently logged back in if they are still "logged in" to Hydra. For this reason, it is less confusing if you set this to match the `HYDRA_SESSION_LIFESPAN` variable on Reaction Identity service, keeping in mind that `HYDRA_SESSION_LIFESPAN` is in seconds rather than milliseconds.	Default is 24 hours. Override in `.env` as needed.	Default is 24 hours.
`SESSION_SECRET`	A unique key for cookie session verification. See https://www.npmjs.com/package/cookie-session#secret	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`STRIPE_PUBLIC_API_KEY`	This is the public / client key from your Stripe dashboard. Do NOT use your secret key here, and be sure to use your "test" key in all non-production environments.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required only if you are using Stripe for payments.
`SITEMAP_MAX_AGE`	The "max-age" value for the "Cache-Control" header included when serving the `sitemap.xml` file.	Default is `43200` (12 hours). Override in `.env` if needed.	Default is `43200` (12 hours).

Identity

Variable Name	Description	Local Development	Deployments
`METEOR_DISABLE_OPTIMISTIC_CACHING`	For local development only, set this to `1`.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Don't set
`METEOR_WATCH_POLLING_INTERVAL_MS`	For local development only, set this to the number of milliseconds to wait between polling for file changes, which makes Meteor perform better in a Docker container.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Don't set
`MONGO_OPLOG_URL`	The oplog URL for the MongoDB deployment.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`MONGO_URL`	The MongoDB database URL.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`PORT`	The port to run the Node server on, in the container. Recommend `4100`.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`API_URL`	A Reaction API URL that is accessible from browsers and accepts GraphQL POST requests over HTTP.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`HYDRA_ADMIN_URL`	The internal Hydra admin URL with port	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set. (Set to `http://hydra:4445` unless you have changed the port to something else in your Hydra config.)
`HYDRA_TOKEN_URL`	The full internal URL for Hydra's token endpoint. Usually something like `http://hydra:4444/oauth2/token`.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`HYDRA_OAUTH2_ERROR_URL`	A public page to redirect to whenever there is an error communicating with Hydra.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Technically optional, but errors will be shown on a less pretty default page if you don't set this.
`HYDRA_SESSION_LIFESPAN`	The maximum age in seconds for the storefront session cookie, which is used for authentication. It can be helpful to set this to match the `SESSION_MAX_AGE_MS` variable on the storefront, keeping in mind that `SESSION_MAX_AGE_MS` is in milliseconds rather than seconds.	Default is `86400` (24 hours). Override in `.env` if needed.	Default is `86400` (24 hours).
`MOCK_TLS_TERMINATION`	If `true`, adds `"X-Forwarded-Proto": "https"` header to the Hydra OAuth PUT requests.	Default is `false`. Override in `.env` as needed.	Default is `false`.
`OAUTH2_CLIENT_DOMAINS`	Comma-separated list of allowed origins for the token refresh `Access-Control-Allow-Origin` header.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required for token refreshing from clients to work
`ROOT_URL`	The canonical root public URL for the Reaction Identity server.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.

Admin

Variable Name	Description	Local Development	Deployments
`METEOR_DISABLE_OPTIMISTIC_CACHING`	For local development only, set this to `1`.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Don't set
`METEOR_WATCH_POLLING_INTERVAL_MS`	For local development only, set this to the number of milliseconds to wait between polling for file changes, which makes Meteor perform better in a Docker container.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Don't set
`MONGO_OPLOG_URL`	The oplog URL for the MongoDB deployment.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`MONGO_URL`	The MongoDB database URL.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`PORT`	The port to run the Node server on, in the container. Recommend `4080`.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`PUBLIC_GRAPHQL_API_URL_HTTP`	A Reaction API URL that is accessible from browsers and accepts GraphQL POST requests over HTTP.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`PUBLIC_GRAPHQL_API_URL_WS`	A Reaction API URL that is accessible from browsers and accepts GraphQL WebSocket connections. Usually the same as `PUBLIC_GRAPHQL_API_URL_HTTP` but replace `http` with `ws`. If this is set, GraphQL subscriptions will be enabled in browser code.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Optional, but any admin pages that rely on GraphQL subscriptions will not work without this set.
`PUBLIC_FILES_BASE_URL`	A full public URL that has /assets/files and /assets/uploads endpoints for uploading and downloading files. Typically this is the API service root URL.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`PUBLIC_I18N_BASE_URL`	Required. A full public URL that has /locales/namespaces.json and /locales/resources.json endpoints for loading translations. Typically this is the API service root URL.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`PUBLIC_STOREFRONT_HOME_URL`	Required. The URL for your storefront home page. This is only used as fallback if a URL isn't set for the shop.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.
`ROOT_URL`	The canonical root public URL for the Reaction Admin server.	Has the correct value for local development in `.env.example`. Override in `.env` as needed.	Required. There is no default and the service will not start without this set.