Build arguments

Docker build arguments and static service environment variables

Build arguments are key-value pairs that are used to initialize a build with either docker-compose or static service environment variables. A static service is any service that doesn't require a container. Visit our guide to static service deployment for more details.

Build arguments can be global and used for all your applications, or specific to a single application.

You can add global build arguments to your global Configuration under the Builds tab. Add secret environment variables only relevant to a single application to App Settings in the "Advanced Settings" section to prevent exposing them to other containers.

Add account-level build arguments

Navigate to Configuration. Select Build Arguments.

Build Arguments Setting

An example use case for global build arguments is an API key for a static build.

Using secrets as build arguments

Read about how secrets are referenced from SSM or the Release Secrets Manager in Referencing cloud secrets.

Environment variables and environment-specific variables are not accessible in the docker build step, so you need to use build arguments as explained in this guide.

In Docker, regular build arguments using the ARG=SOMEVAL format are stored in the Docker image and can be retrieved if someone has access to your image or repository. This may not be a problem for private images unless you store private keys or sensitive information that should not be exposed, even internally.

To safely access secrets in Docker builds, Release recommends using Docker secrets. To access the secret, you need to make some changes to your Dockerfile.

• You can enter your secret directly as a string (Release stores all values encrypted in the database for you), but it's preferable to create a secret or use an existing secret in one of the supported secrets managers. Secrets stored in secrets managers cannot be retrieved from the UI, which adds a layer of security over your secrets.

• Click the padlock icon to convert the secret or secret reference to a Docker secret. Release will mount the value at a file location you can specify later.

• The Docker secret will be available with the same ID as the key you specified, and will be mounted under /var/secrets/ID in the file system. For example, in your Dockerfile, locate your build argument access code, which will look something like this:

ARG API_TOKEN
RUN API_TOKEN=$API_TOKEN start_server.sh

Now change it to look like this:

RUN --mount=type=secret,id=API_TOKEN API_TOKEN=$(cat /run/secrets/API_TOKEN) \
    start_server.sh

• (Optional) In some cases, startup scripts can automatically read build arguments as environment variables if you use the _FILE convention. In this documentation example from Docker, the startup script knows to access the value of API_TOKEN from the file location pointed to by API_TOKEN_FILE. However, this convention only applies under certain circumstances, so be sure to check if it will work in your case.

Add application-level build arguments

Navigate to the Settings tab within an application. Select Build Arguments. The application-specific build arguments will override the account-wide build argument settings.

Navigating to App-Level Build Args under Application Advanced Settings

Notice how USERNAME is inherited from the account-level build arguments, while API_TOKEN is overridden by this application.