Environment variables hold your app's configuration, such as API keys, feature switches and database connection strings. You set them per project, and HCode passes them to the running app and to automatic builds.
Add or change a variable
- Open the project and go to Settings, then the Environment variables section.
- Type the name in Key and the value in Value.
- Tick Secret if the value should be hidden in the dashboard.
- Click Add.
- Click Save changes.
Nothing is stored until you click Save changes. Until then the page shows "You have unsaved changes" at the bottom.
To change a value, edit it in the list and save. To remove a variable, click the cross next to it and save.
Names may use capital letters, digits and underscores, and can't start with a digit, for example DATABASE_URL or STRIPE_KEY_2. Anything else is refused with "Env var keys must be uppercase (A-Z, 0-9, _)." If you add the same name twice, the last one is kept.
Secret and plain values
Every value is stored encrypted, whether or not it is marked Secret. The difference is what the dashboard shows afterwards: a secret's value is never sent back to the page, and appears as dots. To replace a secret, click into the field and type the new value. Leaving it untouched keeps the old value when you save. Secret and plain values reach your app in the same way.
When changes take effect
Saving doesn't restart anything. Your running app gets the new values the next time you:
- click Restart, which starts a fresh copy of the current release with the new values (see Start, stop and restart), or
- deploy, which also gives them to the build.
A deploy reads the variables when it starts, so a change saved while a deploy is running waits for the next one.
Where variables are available
| Automatic build | Dockerfile build | Running app | |
|---|---|---|---|
| Your environment variables | Yes | No | Yes |
Automatic builds get your variables as build secrets, so a build step that reads DATABASE_URL or a NEXT_PUBLIC_* variable sees your value, and the value is not stored in the built image. A few names are never passed to the build: PORT, PATH, HOME, HOSTNAME, PWD, OLDPWD, SHLVL, SHELL, USER, TMPDIR, LD_PRELOAD, LD_LIBRARY_PATH, anything starting with CP_, DOCKER_, BUILDKIT_ or BUILDX_, names that start with a digit or use characters other than letters, digits and underscores, empty values, values larger than 64 KiB, and anything past the build's limit on the number of secrets. The build log lists the names it left out. They still reach the running app.
Dockerfile builds don't get your environment variables. Their build-time inputs are the build args and build secrets set in the Dockerfile settings (see Dockerfile builds).
In build logs, any value of 4 characters or more is replaced with [redacted:NAME]. See Build logs.
The Runtime version (optional) setting for automatic builds is saved as one of these variables. See Runtime versions.
PORT is set by HCode
HCode sets PORT to the project's runtime port when the app starts, and replaces any PORT you set yourself. Make your app listen on 0.0.0.0 and the port in PORT. To change the port, change Runtime port in Settings (see Project settings).
Database connection strings
HCode doesn't add your databases' connection details to the app for you. Copy the connection string from the project's Databases tab into a variable such as DATABASE_URL (see Databases overview).
If you paste the external address of a database in the same project into DATABASE_URL, POSTGRES_URL, POSTGRESQL_URL, a name ending in _DATABASE_URL, _DB_URL or _CONNECTION_STRING, or a host variable such as DB_HOST or PGHOST, HCode swaps in the database's private address when it deploys or restarts the app, and for a PostgreSQL URL it also sets sslmode=disable. A port in the value becomes the database's own port (5432 for PostgreSQL), and so does a matching port variable such as DB_PORT or PGPORT. Traffic then stays on the project's private network.