How to manage environment variables and secrets

There are two types of environment variables:

• frontend environment variables. A frontend environment variable is visible through the client browser.

• secret environment variables. A secret environment variable can only be queried by the backend and will not be available in the client browser.

Environment Variable Substitution

frontend environment variables are substituted using the env. prefix where secret environment variables use the secrets. prefix.

Example:

export MY_ENV=...
export PORTAL_SECRET_MY_SECRET=...

In the above example, MY_ENV will be used as a frontend environment variable and should therefore be referenced as ${ env.MY_ENV } when used in configuration.

PORTAL_SECRET_MY_SECRET is a secret and needs to be referenced as ${ secrets.MY_SECRET }.

Note: Please note that secret environment variables need to be prefixed with PORTAL_SECRET_ to properly be identified as secrets.

Visibility validation

The @visibility keyword defined in the configuration schema is validated when adding an environment variable as configuration to Portal.

That means if an environment variable referenced in configuration is of type frontend - such as ${ env.MY_ENV } - but the @visibility in the schema of the field it is used in is of type secret, use of that value will fail.

Read more about configuration visibility here.

Required environment variables

Portal requires a set of environment variables to be defined in order for it to successfully start up.

Name	Type	Purpose
PORTAL_DATABASE_HOST	frontend	Database host
PORTAL_DATABASE_PORT	frontend	Database port
PORTAL_DATABASE_USER	frontend	Database user
PORTAL_SECRET_DATABASE_PASSWORD	secret	Database password
PORTAL_CONFIG_ENCRYPTION_KEY	frontend	Key for encrypting database content
PORTAL_ROOT_USER_PASSWORD	frontend	Password for the root user
PORTAL_SECRET_BACKEND_KEY	secret	Key for signing service-to-service tokens
PORTAL_BASE_URL	frontend	The public URL of the frontend

If any of these environment variables are not defined an error is thrown:

NotAllowedError: Required environment variable(s) PORTAL_DATABASE_HOST,PORTAL_CONFIG_ENCRYPTION_KEY was not found

Referencing secret values using the env var pattern

Whenever using a value that is considered a secret it is recommended to pass that value in as an environment variable and then referencing that value using the ${ secrets.ENV } syntax.

As an example, the clientSecret for an authentication provider can be passed into the container using environment variables like this:

docker run --rm \
  ...
  -e PORTAL_SECRET_GITHUB_CLIENT_SECRET=<clientSecretValue> \
 spotify/portal

These can then be referenced in config as ${ secrets.GITHUB_CLIENT_SECRET}.

Examples in the Config Manager

Below is an example of how an environment variable and a secret is referenced in the Config Manager.

In the example, the variables are set up and referenced as follows:

• export GITHUB_CLIENT_ID=... referenced in the Config Manager UI as ${ env.GITHUB_CLIENT_ID }
• export PORTAL_SECRET_GITHUB_CLIENT_SECRET=... referenced in the Config Manager UI as ${ secrets.GITHUB_CLIENT_SECRET }