Environment variables

Set configuration and secrets per app, outside your repository. Where a variable is visible — during the build, in the running app, or in the browser — depends on its name.

Add variables#

Open the app and go to Environment. Variables apply to production and to every preview of the app.

Names use letters, digits and underscores, cannot start with a digit, and are at most 128 characters: DATABASE_URL, NEXT_PUBLIC_API_URL.
Values can be up to 32,768 characters.
Values are encrypted when stored and are never shown again after you save them. To change one, set it again.

Where each variable is visible#

Variable	During the build	In the running app	In the browser
Starts with `NEXT_PUBLIC_` or `PUBLIC_`	Yes, as a build argument	No — its value is already built into your code	Yes, once your framework embeds it
Any other name	Yes, for Node, static and Hugo builds	Yes	Only if your build embeds it

Public variables

A variable whose name starts with NEXT_PUBLIC_ or PUBLIC_ is meant for client code. It is passed to the build, where your framework writes its value into the JavaScript sent to browsers, so anyone visiting the site can read it. Never put a secret in one.

Because the value is built in, changing it only takes effect when the app is rebuilt — a rollback keeps the value that version was built with.

Other prefixes your framework embeds

Vite, Create React App and Nuxt embed variables with their own prefixes — VITE_, REACT_APP_, NUXT_PUBLIC_. These reach the build like any other variable, and your framework embeds them as usual, so they end up public in the same way. They are also set in the running app.

Everything else

Every other variable is set in your running app’s environment. For Node, static-site and Hugo apps it is also available while your build script runs, so a build that fetches data or checks configuration can use it. It is not available while dependencies are being installed.

For Python, PHP, Go, Rust, Java and Ruby apps, variables are available at runtime only. If your build needs them, use your own Dockerfile, below.

With your own Dockerfile#

When you bring a Dockerfile, variables reach your build in two ways.

Public variables: build arguments

Declare each one you use with ARG:

Dockerfile

ARG NEXT_PUBLIC_API_URL
RUN npm run build

Other variables: a build secret

Every other variable is provided as a BuildKit secret with the id ahura-env: a file of export NAME='value' lines. Mount it only in the step that needs it, so no value is written into an image layer:

Dockerfile

# syntax=docker/dockerfile:1.7
RUN --mount=type=secret,id=ahura-env \
    . /run/secrets/ahura-env && npm run build

At runtime, every variable except public ones is set in your container’s environment, exactly as for apps we build.

Keep secrets out of logs#

Something missing or wrong on this page? Tell us, and quote the page title.