Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 37 ยท Add-ons and Config

Config Vars

Manage Heroku config vars: set, read and remove them with the CLI, read them safely in your code, parse DATABASE_URL, and avoid leaking secrets into Git, logs or dashboards.

The same code usually runs in several places: your laptop, a staging app, production. What differs is the configuration: the database address, API keys, feature switches, the log level. Hard-coding those values in the source is a mistake for two reasons. You would need a code change to alter a setting, and secrets would end up in your Git history.

Heroku's answer, and the twelve-factor answer, is to keep configuration in environment variables that the platform supplies to every process. On Heroku these are called config vars.

Setting, reading and removing

CONSOLE
$ heroku config:set SECRET_KEY=change-me LOG_LEVEL=info
$ heroku config
$ heroku config:get LOG_LEVEL
$ heroku config:unset LOG_LEVEL
$ heroku config --json
$ heroku config --shell
  • config:set takes one or more KEY=value pairs and creates a new release; the dynos restart to pick the change up. Setting several at once makes one release instead of several.
  • heroku config lists every var, config:get prints one, and --shell prints them as KEY=value lines you can save into a local .env file.
  • config:unset removes one. config:edit opens an editor for all of them at once.
  • Values with spaces or special characters need quotes in your shell: heroku config:set GREETING="hello world".

In the dashboard they live under the app's Settings tab, in the "Config Vars" section. Both the dashboard and the CLI edit the same thing.

Rules and limits to remember:

  • Names are conventionally UPPER_SNAKE_CASE, and values are strings. Booleans and numbers arrive as text.
  • The total size of all config vars is limited (about 32 KB), so they are for settings and credentials, not for large documents or certificates in bulk.
  • Anyone with access to the app can read the values. Treat the app's collaborator list as part of your security model.
  • Heroku sets a few itself: PORT (for web dynos), DYNO, and one for each attached add-on such as DATABASE_URL. Do not set PORT yourself.

Reading config in code

Every language exposes the environment:

JavaScript
// Node.js
const logLevel = process.env.LOG_LEVEL ?? "info";
Python
# Python
import os
log_level = os.environ.get("LOG_LEVEL", "info")
Ruby
# Ruby
log_level = ENV.fetch("LOG_LEVEL", "info")

Two principles help here. Fail fast for required values: use a lookup that raises when a required var is missing (os.environ["SECRET_KEY"], ENV.fetch("SECRET_KEY")) so the app crashes at boot with a clear message instead of misbehaving later. Convert once at the edge: parse strings into booleans and numbers in one settings module, not all over the code, because "false" is a non-empty string and therefore truthy in many languages.

Config vars from add-ons

When you attach an add-on, the platform sets config vars for you. A Postgres database gives you DATABASE_URL in the form:

TEXT
postgres://user:password@host:5432/dbname

Your database library usually accepts this URL directly. Do not copy it into your code or .env committed to Git: the add-on may rotate credentials, and the config var always holds the current value. See add-ons.

Stand-in: a typed settings loader

This stand-in simulates the environment with a dictionary. It reads required and optional values, converts types in one place and reports every problem at once. It is the pattern many frameworks implement.

Python Stand-in: load settings from the environment

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice DEBUG="false" becomes the boolean False; comparing the raw string in a condition would have been a bug.

Stand-in: parse DATABASE_URL

Add-ons deliver connection details as one URL. Splitting it into parts is something every framework does internally; here it is with the standard library.

Python Stand-in: take a DATABASE_URL apart

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The program masks the password on purpose: do not log connection strings. Logs may be retained, drained to third parties and read by more people than the config page.

Keeping secrets safe

  • Never commit secrets. If one slips in, rotate it (create a new one and revoke the old); deleting the commit is not enough.
  • Do not print config in your app's logs or error pages. Debug pages that dump the environment have caused real breaches.
  • Use a separate value per environment (staging and production must not share keys).
  • Remember that heroku run env prints the whole environment, so limit who can run one-off dynos.
  • Copy config between apps deliberately: heroku config --shell -a staging makes a file you can inspect before you apply it elsewhere.

Config and releases

Each change creates a release, so config has a history: heroku releases:info shows the vars as they were. Rolling back also rolls config back. Because every change restarts dynos, group related changes into one config:set command during busy periods.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What happens when you run heroku config:set?

    Config changes create a release with the same slug and new config, and the dynos restart.
  2. 2. Why does the string "false" cause bugs if used directly as a boolean?

    Environment values are strings. Convert them to real booleans in one settings module.
  3. 3. Where does DATABASE_URL come from?

    Add-ons inject their connection details as config vars, and the platform may update them when credentials rotate.
  4. 4. A secret was committed to Git. What is the right fix?

    Anything that was ever in history must be treated as exposed, so replace the secret.
  5. 5. How should a required setting be read?

    Failing fast gives a clear error at startup instead of strange behavior later.

Summary

  • Config vars are environment variables managed by heroku config:set, get, unset and the dashboard; each change creates a release.
  • Read them with your language's environment API, fail fast on required ones and convert types once.
  • Add-ons supply their own vars such as DATABASE_URL; never hard-code them.
  • Keep secrets out of Git and logs, and rotate any that leak.

Next: Heroku Local and env files