Configuring Environment Variables and Secrets

In this guide, we’ll give a brief introduction to environment variables and secrets and show you how to configure them on Render. Environment variables and secrets allow you to configure your application at runtime without hardcoding values in the source code. Separating the app configuration from code is a core tenet of the twelve-factor app philosophy.

Why Use Environment Variables

Your application will typically run in more than one environment (for example, development and production). Although these instances run the same code, they might still need different credentials and environment-specific configurations. These include things like database connection strings and API keys to external services like S3.

Configuration details stored in the source code make the code brittle and difficult to run in different environments, and credentials checked into version control pose a security risk.

A better solution is to store these details in environment variables and not in the app’s source code. Environment variables are easy to change between deploys without changing any code, let you modify each environment’s configuration in isolation, and prevent secure credentials from being stored in version control. They are a language- and OS-agnostic standard which makes your code more flexible and simplifies your deployment process.

Getting Started with Environment Variables

To set environment variables in your environment, you can use the export command from the terminal.

export KEY=value

The syntax to access these variables from code usually varies by language.

JavaScript:

process.env.KEY;

Python:

import os
os.environ.get('KEY')

Elixir:

System.get_env("KEY")

Most languages also have corresponding libraries to do more sophisticated things with environment variables.

Secret and Environment Configuration Files

In addition to exporting from the terminal, you can also put environment variables in a .env file in which you specify these environment variables. You can then use a library for your respective programming language (e.g. dotenv for Node.js and python-dotenv for Python) to load the file which will dynamically define these variables.

The .env file is usually put at the root of your project and lists the key-value pairs of the environment variables:

KEY1=value1
KEY2=value2

There are other files that help set up your configuration or store secrets like .npmrc files (which are similar to .env files but for npm, a JavaScript package manager), and private keys. To avoid accidentally committing .env to Git, you should add .env to your .gitignore.

Configuring Secrets and Other Environment Information on Render

Render supports environment variables, configuration files, and secrets and lets you manage them at different levels of granularity to simplify your deployment processes:

If you configure your services using the Render Dashboard, you can use either:

1. Per service Environment Variables
2. Environment Groups for use by multiple services

If you use Blueprints:

3. Environment Variables in the Blueprints Spec

1. Per-service Environment Variables

You can use this method if the environment variable is going to be used only by one service.

1. From your Render Dashboard, click on the service that you want to add the environment variable to.

   

2. Click on Environment in the left pane, and then click on Add Environment Variable.

   

3. Enter the Key and Value for your environment variable. You can add multiple environment variables by clicking on the Add Environment Variable button and then clicking Save Changes whenever you’re done.

   

4. Similarly, you can also add Secret files to your project, and they will be available to read at the root of your repo (or Docker context).

   

2. Environment Groups

Environment groups are useful for sharing environment variables across services. You’ll need to create a new group, add environment variables and secret files to it, and link it with the appropriate service(s).

1. From the navbar, click on Env Groups and then New Environment Group.

   

2. Give the group a name and then, similar to method 1 above, you can add environment variables and secret files to it. Then click Create Environment Group.

   

3. Go back to the Dashboard and click on the service you want to associate the environment variables with.

   

4. Click on Environment in the left pane.

   

5. Scroll down to the Linked Environment Groups section and select the Environment Group you just created from the dropdown. Then click Link.

   

6. The environment variable(s) and secret files in the group will be linked to the service. You can link the same env group to other services in the same manner.

   

   If an environment variable with the same key is defined both directly in the service and in a linked env group, the value defined in the service will take precedence.

3. Specifying Environment Variables in the Blueprints Spec

If you are using Blueprints to represent your infrastructure as code, then you can put your environment variables directly in the render.yaml file.

There are various ways in which you can use environment variables in the spec file:

• value can directly specify a literal value.
• fromDatabase lets you fetch the value from a database.
• fromService allows you to fetch the value from another service.
• generateValue lets you create a shared secret for your service.
• sync: false is a placeholder for a value you will enter in the UI when you first deploy.
• envVarGroups lets you define the env groups that we saw in method 2 as code in the Blueprint spec.

More details and examples for these can be found in the Blueprint Specification.