Environment Variables

Environment variables can be configured within your repo to provide them to the server at runtime. This provides more control to the developer than having to make requests to the PB team, who then has to manage all client environments in a single place.

PageBuilder Engine Environment files

Local Development

The system expects you to store environment variables in local dev in two different places. First one is your custom environment variables to go in environment/localhost.(js|json|ts|yaml|yml). Second one is Enginge recognized system variables (listed at the end of this document) in the .env file in the root of your repo (not within the / directory). Note that storing decrypted secrets in the localhost file may present a security vulnerability if those secrets are committed to your repo or are added to an uploaded bundle.

PageBuilder expects system variables to be present in .env file and will not pass through environment variable values defined in the bash session of your host, because when running PageBuilder locally, there are multiple layers, of build, docker containerization happens which container orchestration relies the physical .env file for reading your system variables. Your custom environment variables has to be located in environment/localhost.(js|json|ts|yaml|yml) which gets linked to downstream containers already.

Production (non-local) Development

Environment values in all non-dev (i.e., “production”) environments are expected to be stored and named in one of the following formats:

• /environment.(js|json|ts|yaml|yml)
• /environment/index.(js|json|ts|yaml|yml)
• /environment/${environment}.(js|json|ts|yaml|yml)

Example

Encrypted values are only decrypted in the production environment and are provided as-is in local development. To address this, local environment variables defined in the .env file take precedence.

Local Development

In this example, the localhost environment’s .env file sets API_CREDENTIALS to the unencrypted basic-auth credentials user:password:

API_CREDENTIALS=user:password

Production (non-local) Development

In this example, all environments set DEFAULT_TTL to 240, all environments except for org-sandbox set API_CREDENTIALS to the decryption of the string AWS_ENCRYPTED_CIPHER_TEXT, and the org-sandbox environment sets API_CREDENTIALS to the decryption of the string SANDBOX_AWS_ENCRYPTED_CIPHER_TEXT.

The /environment.js file:

export default {
  DEFAULT_TTL: 240,
  API_CREDENTIALS: "%{AWS_ENCRYPTED_CIPHER_TEXT}"
}

The /environment/org-sandbox.js file:

export default {
  API_CREDENTIALS: "%{SANDBOX_AWS_ENCRYPTED_CIPHER_TEXT}"
}

Access to Environment variables from your code

You may read environment variables from a JavaScript file by importing the fusion:environment module.

Example

Define the OMDB_API_KEY environment variable in the local-development .env file:

OMDB_API_KEY=a1b2c3d4

Import the OMDB_API_KEY environment variable in a sample content source /content/sources/movie-find.js:

import { OMDB_API_KEY } from 'fusion:environment'

const resolve = (query) => {
  const requestUri = `https://www.omdbapi.com/?apikey=${OMDB_API_KEY}&plot=full`

  if (query.hasOwnProperty('movieTitle')) return `${requestUri}&t=${query.movieTitle}`

  throw new Error('movie-find content source requires a movieTitle')
}

export default {
  resolve,
  schemaName: 'movie',
  params: {
    movieTitle: 'text'
  }
}

Important

The fusion:environment module only reads encrypted environment values during server execution; they are hidden from client-side code to mitigate the security risks of exposing them to the Internet. Unencrypted values are always available and should not contain sensitive information.

Encryption using “Secret Manager”

You may find it necessary to use “secret” environment variables, such as API credentials when building a Feature Pack. In local development, it’s OK to add these unencrypted credentials to your .env file and use them. However, PageBuilder Engine needs a way to access these “secret” variables in production environments without developers adding unencrypted credentials directly to their bundles.

To solve this problem, PageBuilder Engine allows developers to include “secret” variables that have been encrypted with the proper KMS key to their environment variables, provided that these variables are surrounded by “percent-braces” characters (e.g. %{MY_ENCRYPTED_TEXT_HERE}). The encrypted values will then be decrypted at deploy-time and available to your bundle without being committed to version control.

To access to PageBuilder Secret Manager, navigate to your Arc Admin, then PageBuilder and Deployer tool under “Developer Tools” top menu. After Deployer opens, navigate to “Secrets” tab to use this tool. Copy the unencrypted value you wish to keep “secret” and paste it into the “encrypt” text input at the top of the page, then click the “encrypt” button. You should get back an encrypted value that looks similar to this:

AQECAHhPwAyPK3nfERyAvm................liUhMKabNeSyk

This encrypted value is now safe to be stored in our git repository and added to our /environment/index.js file inside of “percent brace” control characters, like so:

export default {
  OMDB_API_KEY: "%{AQECAHhPwAyPK3nfERyAvm................liUhMKabNeSyk}"
}

Since this KMS key is assigned on a per-client, per-environment basis, Fusion will automatically decrypt this variable during deployment so it can be used reliably.

Local Development Environment Variables

Note

Starting with Engine 4.x, only PageBuilder Engine system environment variables will be recognized from .env file. If you place any custom environment variables in .env file, they will not be available in your build and runtime code. See Engine 4.x Migration notes for more details about this change.

Having these environment variables in environment/*.json files will not work. They have to be present in .env file in your project root folder.

The following environment variables govern special behavior in PageBuilder Engine. They are set automatically set by the PageBuilder Deployer when creating a new deployment and can be set in .env files for local development.

Important

Do not set these in your non-local environment files. They will either be ignored or cause unexpected results that are difficult to troubleshoot.

FUSION_RELEASE — This environment variable controls which release of PageBuilder Engine is downloaded when you run npx fusion start. You can set it to any release version (e.g. 5.0.1) or you can set it to latest if you want to always work off the latest release. We recommend using latest to catch potential breaking changes early.

CONTENT_BASE — This represents the default base path or domain for content sources that use resolve. It is appended automatically to the beginning of relative urls paths returned from resolve. This typically points back to your Arc API domain. (e.g. https://api.client-name.arcpublishing.com)

It is not appended automatically to requests made from fetch content sources.

ARC_ACCESS_TOKEN — This stores the value of an access token for the Arc API. This value is automatically added as an HTTP Bearer token to any requests generated by resolve that fulfill the following conditions:

• The URL begins with the value of CONTENT_BASE
• The URL does not include any Basic Authentication credentials

It is not appended automatically to requests made from fetch content sources.

CONTENT_TIMEOUT — This environment variable controls the maximum time (in milliseconds) a content source can take before it is terminated. The default value is 5000.

USE_AXE — This environment variable controls if react-axe should be run in the browser. It is a boolean and defaults to false.

MINIFY — This environment variable controls if Webpack should minify and tree-shake the final bundle. It is a boolean and defaults to false. Turning it on will cause your build times to be slower locally. This is always enabled in non-local environments.

DEFAULT_ARC_SITE — This environment variable controls the value of the _website query parameter is when it is not specified. It defaults to an empty string.

FUSION_GENERATE_TRACING_JSON — This environment variable controls if a calls.json file should be generated locally with content source call data. It is a boolean and defaults to false. See Request Tracing for more information.

DEBUG — This environment variable allows printing out specific render events. Developers can enable all events with providing value *, or specify which events to see in the command line output like DEBUG=arc.fusion.render.error,arc.fusion.content.fetch.error. By default these events are not shown in the command line output.

SLS_RELOAD_HANDLER — This environment variable controls how Serverless stack (that simulates rendering engine in local environmetns) cache. We disable cache to engine renders in local environment. True value disables the cache, false value enables it. By default it is set to true.

ENGINE_HEAP_SIZE — To configure the memory limits for engine process. This variable is used by Docker to set the actual rendering process container (engine Lambda) to have more memory for rendering more complex pages rendering many features and executes complex content sources. Default value is 2048 (2GB).

WEBPACK_HEAP_SIZE — To configure the memory limits for build process. This variable is used by Docker to set the build process container (webpack) to have more memory for building more complex bundles. Build process is independent from the actual render happens. If you bundle have more features, output types, content sources, you may need to increase this. Default value is 4096 (4GB).

Special Environment Variables

The following environment variables change the bundle behavior/how the bundle is compiled. In most cases, they are not automatically set by the PageBuilder Deployer and are off by default.

BLOCK_DIST_TAG — This environment variable controls the tag used for Themes Blocks that don’t specify a version in blocks.json. It is a string and the default value is stable.

FUSION_SERVICE_WORKER — This environment variable controls if the service worker is included in the compiled bundle. It is a boolean and the default value is false.

FUSION_SKIP_UNSAFE_URL_SANITIZATION — This environment variable controls if Fusion should sanitize the final output. By default, PageBuilder Engine will remove all strings (enclosed by quotes) that are URLs in the .arcpublishing.com domain. The only exceptions are *.cdn.arcpublishing.com, *.images.arcpublishing.com, *.video.arcpublishing.com, and *.video-player.arcpublishing.com. This helps to protect your site from exposing Okta protected URLs. It is a boolean and the default value is false.

FUSION_ENABLE_TRACING — This environment variable controls if PageBuilder Engine injects headers and logs tracing information for content sources. It is a boolean and defaults to false. See Request Tracing for more information.