Environment Variables and Secrets

If there's information or certain behavior of your project that needs to differ depending on if it's running locally or on Now, environment variables are the perfect solution.

Not only do they avoid having to hardcode these settings (which is very important for sensitive information, which can't just be version-controlled), but they also allow you to access information about the current environment your code is running in.

There are various ways to define environment variables, let's explore these options.

From the CLI

The first way of defining environment variables is by specifying them using the -e option in the terminal. Assuming that you'd like to add an environment variable named "DATABASE_NAME" with a value of "test", this is how the command should look:

now -e DATABASE_NAME="test"

Defining an environment variable using the terminal.

This will deploy the project within the current directory and assign the environment variable. In your code, you can then access it through the language's default environment variable accessor. For example, with Node.js:

process.env.DATABASE_NAME

Accessing an environment variable in Node.js.

Just like defined before, the content of this global variable will be "test".

From now.json

The second way of defining environment variables is made specifically for when the content of the variables you'd like to define will stay the same for every new deployment.

If that fits your project, simply add the env property to your now.json file:

{
  "env": {
    "DATABASE_NAME": "test"
  }
}

An example now.json configuration file specifying an environment variable.

As you may have already noticed, this property holds an object which can contain as many environment variables as you need. Once again, this will assign an environment variable called "DATABASE_NAME" with a value of "test" to your deployments.

You can also pass environment variables to Build processes on a deployment via the build.env configuration property:

{
  "build": {
    "env": {
      "MY_KEY": "this is the value",
      "SECRET": "@my-secret-name"
    }
  }
}

An example now.json configuration file specifying build environment variables.

The configuration above will pass the static env keys; MY_KEY, and SECRET to all builds. The SECRET env key is dynamically set from the my-secret-name secret.

Securing Environment Variables Using Secrets

Sometimes you need to store sensitive information on the deployment that should only be accessible by the code that's running in it. This can be accomplished by using now secret, which allows you to store data needed by your apps to function (such as API tokens or passwords) in a secure way.

Once you store a secret, its contents are no longer accessible directly by anyone. They can only be exposed to deployments as environment variables, which we'll show below. Let's create a secret with an API key:

now secret add acme-api-key my-value-here

Creating a secret with an API key.

Once created, you can rename the secret with now secret rename or delete it completely with now secret rm. For more examples and the full list of options and commands, run now help secret.

Note: The name of a secret cannot be longer than 100 characters.

After creating the secret, you can assign it to an environment variable. Here's an example of doing this using a command:

now -e MY_VARIABLE=@acme-api-key

Assigning a secret to an environment variable using the terminal.

You can also assign the secret to an environment variable using the env property of your now.json file:

"env": {
  "MY_VARIABLE": "@acme-api-key"
}

An example now.json configuration file assigning a secret to an environment variable.

Both of the solutions above will create an environment variable called "MY_VARIABLE" and assign the content of the "acme-api-key" secret to it (which is "my-value-here").

Further Tips

We implemented some sweet functionality into the command line interface and the platform, which makes adding environment variables and secrets to your deployment even easier.

For example, you can also include -e multiple times:

now -e API_KEY=@my-key -e APP_NAME="ZEIT, Inc"

Assigning multiple environment variables in one command using the terminal.

Additionally, there is also the capability to inherit from your shell environment. To do so, just skip the =value portion of the argument:

now -e MY_SHELL_VAR

Inheriting an environment variable from the shell environment.

Users of the API can access the environment variables feature through the secrets endpoint.

Built-In Variables

By default, all deployments expose the NOW_REGION environment variable to lambdas which provides the region that the lambda was deployed to.

Reserved Variables

The following environment variables are reserved and therefore unavailable for use:

  • AWS_REGION
  • AWS_DEFAULT_REGION
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_KEY
  • AWS_SECRET_ACCESS_KEY
  • AWS_EXECUTION_ENV
  • AWS_LAMBDA_LOG_GROUP_NAME
  • AWS_LAMBDA_LOG_STREAM_NAME
  • AWS_LAMBDA_FUNCTION_NAME
  • AWS_LAMBDA_FUNCTION_MEMORY_SIZE
  • AWS_LAMBDA_FUNCTION_VERSION
  • AWS_SESSION_TOKEN
  • NOW_REGION
  • TZ
  • _HANDLER
  • LAMBDA_TASK_ROOT
  • LAMBDA_RUNTIME_DIR

Using either, or any, of these environment variables, will result in the deployment failing.