Build-Time Environment Variables and Secrets
If you are looking for information covering environment variables and secrets to use within your app, read our guide on Run-Time Env and Secrets.
There are multiple stages involved in the process of deploying an app, for example installing dependencies. For Now to recognize that an app needs a build step, that app will need a Dockerfile
, which will contain all of the build steps for the app.
Using a Dockerfile
is to define the process of an app being built on Now, which will deploy the app after the build process using the Dockerfile
configuration.
During the build process, information that needs to be used at that time might not be safe to hard code into the app or preferred to be kept in a configuration file for the app. In this case, Now supports a method that allows assigning an environment variable or secret for deployments to use during build time.
To use custom environment variables or secrets in the build process on Now, there are two methods.
Provide a Now deployment with environment variables directly from within the now.json
configuration file. To do so for the build step, the environment variables must be within the build.env
property. For example:
{ "build": { "env": { "NODE_ENV": "production" } } }
Listing the `NODE_ENV` build environment variable with the value of `production` within a `now.json` configuration file and within the `build.env` property.
Using the built-in --build-env
parameter to pass environment variables to the build stage of a Now deployment. For example, the following command will give the NODE_ENV
environment variable the value of production
:
Setting the `NODE_ENV` build environment variables to have a value of `production` with Now CLI
Secrets are a way to keep information from being displayed in configuration or in code. Now will store secrets associated with an account or team ready for use with environment variables.
To use secrets with Now in the build stage, the first step is to add a secret with the now secret
command in Now CLI.
Adding the `npm-token` secret to an account or team, with the example of a value
The second step to using a secret at build-time is to pass it as an environment variable, using both methods above but by using an @
symbol before the value.
For example, in a now.json
configuration, it will look like this:
{ "build": { "env": { "NPM_TOKEN": "@npm-token" } } }
Using the `npm-token` secret with an environment variable within a `now.json` configuration.
It is also possible to use secrets with Now CLI using the same method of using the @
symbol before the value
Read more about secrets within Now for more examples and information.
With environment variables set up using one of the methods above, with secrets or not, use them within the build step using a Dockerfile
.
Having a Dockerfile
gives Now the context that a build step exists for an app. Within that Dockerfile
, use environment variables set up in previous steps (including those with values associated with secrets) using the ARG
instruction.
For example, to use the NPM_TOKEN
environment variable from the last step use the following in a Dockerfile
:
ARG NPM_TOKEN
Creating an ARG variable with the value of an earlier created environment variable
The Dockerfile
and Now will associate the value of that ARG
with the NPM_TOKEN
environment variable. Then, subsequently use this value by referencing the ARG
with the same name with a $
prefixing it.
RUN echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > ~/.npmrc
Using an environment variable and `ARG` in conjunction to output a valid `.npmrc` for private npm
Note that by default an app with a
Dockerfile
deployment will be detected as a Docker deployment. Make sure to mark an app as"type": "static"
within the now.json configuration if the app should be deployed and built as static using theDockerfile
.
To use private npm packages, npm requires that apps provide an auth token. It is not always possible or safe to hardcode this auth token, so environment variables and secrets are the features available to manage this.
To start, a new token is needed. npm will create a new token using the command npm token create --read-only
. It is better to keep this token secret to avoid others gaining access to private packages. To protect the token from reaching others outside of those intended, the now secret
command will take the token and associate it with an account or team ready to be used with environment variables.
Adding the `npm-token` secret to an account or team.
Once the secret is added, it can be used in a now.json
configuration using environment variables.
{ "build": { "env": { "NPM_TOKEN": "@npm-token" } } }
This is also possible with the Now CLI method.
The
now.json
configuration can be extended beyond just abuild.env
property. Read more about configuring deployments.
With the environment variable NPM_TOKEN
set to the value of the npm-token
secret, which contains an npm auth token, it is ready to use.
This example describes how to install dependencies for a static app build. The Dockerfile
holds an ARG
instruction that relates to the recently created NPM_TOKEN
environment variable.
FROM mhart/alpine-node # Retrieve and relate to the `NPM_TOKEN` environment variable ARG NPM_TOKEN # Print into `.npmrc` with a string using the `NPM_TOKEN` ARG RUN echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > ~/.npmrc WORKDIR /usr/src # Install dependencies COPY package.json yarn.lock ./ RUN yarn COPY . . # Run build and export RUN yarn build && yarn export -o /public
Note that the usage of the `ARG` instruction starts with a `$`. This is necessary for Docker to recognize this as an ARG instruction reference.
With the Dockerfile
complete, the project is ready to be deployed on Now:
Through the deployment lifecycle, the build stage will execute with the configuration defined in the Dockerfile
including that of the environment variables and secrets.
An example repository is available to give a more in-depth look at a project that uses build-time environment variables and secrets.