How to Configure Your Preview With Env Vars and Docker Build-Args

Your project probably needs to run in different environments:

  • On your local machine during development,
  • on the CI/CD server when running your tests,
  • on your staging system
  • in WunderPreview
  • and eventually on your production environment.

For every one of those environments, your project needs different settings. Sometimes you need to set a switch for the compiler. Or you need to use different API keys for production and staging. Depending on the environment you need to connect to a different database, or seed the database with test data.

The easiest way to enable this kind of portability in your project is to separate code from config. Environment variables (or env vars) are a good place to store your configuration. Your project can read the env vars, and if not present fall back to default values.

In WunderPreview you have the possibility to define environment variables in the settings of your GitHub repository in WunderPreview.

Screenshot of environment variables settings in WunderPreview
Environment variables settings in WunderPreview

Those configured environment variables can be used in two ways:

  • You can use them during the run-time of your preview like normal environment variables that are set on your server.

  • These environment variables are also given as build-args to the "docker build" command when the preview builds. So you can use them during the build time of the preview.

In addition to the environment variables you define in your settings, WunderPreview also sets some special env vars for you (more on those WunderPreview environment variables later)

Using env vars during run time

You can configure environment variables in the WunderPreview settings screen of your repository.

All the environment variables you configure here will be injected into the running preview so they are available during the run-time of the preview.

Consume them as you would consume any other environment variable.

WunderPreview specific env vars

WunderPreviews injects one special env var in every preview. The variable IS_WUNDERPREVIEW has the value 1 and just tells your project, that it is running inside WunderPreview.

With this variable, you could change the database you want to use or you could start a script in your Dockerfile that generates some test data you want to use when running in WunderPreview.

If you have created a database in your WunderPreview Account there are a number of additional env vars for you to use:

  • WDPR_DB_USERNAME
  • WDPR_DB_PASSWORD
  • WDPR_DB_HOST
  • WDPR_DB_PORT
  • WDPR_DB_DATABASE
  • WDPR_DB_CONNECTION_STRING

See How to connect to my WunderPreview database for detailed information about those env vars.

Using WunderPreview specific env vars during run-time

The environment variable IS_WUNDERPREVIEW (and the others in the list above) are just available in your container. You do not need to do anything to have them during run-time in your container.

Using WunderPreview specific env vars to set my custom env vars.

In WunderPreview you will get an env var called WDPR_DB_USERNAME that contains the username to use when connecting to your WunderPreview database.

But maybe you already have another env var called DATABASE_PG_USER that you all over the place in your code.

In this case, you can also use the WunderPreview env vars as the value of your env vars in your settings. The example above would look like this in your settings:

Screenshot of using WunderPreview env vars as value of other env vars.
Screenshot of using WunderPreview env vars as value of other env vars.

Using env vars during build of the container

To create your preview, WunderPreview builds your Dockerfile.

WunderPreview will give all the environment variables you defined in the repository settings as a build argument to the docker build command.

As an example: if you define a variable NODE_ENV with the value production the docker build command will look something like this:

docker build --build-arg NODE_ENV=production --tag myprj:v1 --file Dockerfile .

To use this variable during build-time in your Dockerfile you need to use the ARG instruction in your Dockerfile. Like so:

ARG NODE_ENV
ENV NODE_ENV=$NODE_ENV

For more information on how to use environment variables in your Dockerfile see the official documentation:

https://docs.docker.com/engine/reference/builder/#arg

Using WunderPreview specific env vars during build-time

If you want to use use the IS_WUNDERPREVIEW env variable in a script that you call in your Dockerfile you need to add this to your Dockerfile:

ARG IS_WUNDERPREVIEW
ENV IS_WUNDERPREVIEW=$IS_WUNDERPREVIEW

With this you consume the build argument given by WunderPreview and set it in the environment during the build process.


Do you have any questions or remarks? Just send us an email to hi@wunderstack.io. We are happy to hear from you!

Keep things moving with automated previews.

Screenshot of WunderPreview Dashboard