Skip to content

Environments

This page documents how to access environment variables in your templates. There are two main ways to use environment variables:

  • The .Env variable (direct access to all environment variables through a map)
  • The env function (recommended for most cases since it supports default values)

Both approaches have their own use-cases and trade-offs. Read below to understand when to use each.

Variables

.Env

The .Env variable is a map containing all environment variables as key-value pairs. You can access variables directly using the map syntax.

Syntax

1
{{ .Env.<variable> }}
  • If the environment variable is set, its value is returned.
  • If not set, an error is raised.

Warning

There is no way to provide a default value using this method.

Examples

Usage
1
NGINX_WORKER_PROCESSES=4
Template
1
{{ .Env.NGINX_WORKER_PROCESSES }}
Output
1
4

1
Template
1
{{ .Env.NGINX_WORKER_PROCESSES }}
Output
1
error: map has no entry for key "NGINX_WORKER_PROCESSES"

Functions

env

The env function allows you to read environment variables directly in your templates. It supports an optional default value, making it robust for missing variables.

Syntax

1
{{ env <variable> <default> }}
  • If the environment variable is set, its value is returned.
  • If not set, the default value (if provided) is returned.
  • If not set and no default is provided, an error is raised.

Examples

Usage (without default value)
1
NGINX_WORKER_PROCESSES=4
Template
1
{{ env "NGINX_WORKER_PROCESSES" }}
Output
1
4

1
Template
1
{{ env "NGINX_WORKER_PROCESSES" }}
Output
1
error: environment variable REQUIRED_SECRET is missing or empty
Usage (with default value)
1
NGINX_WORKER_PROCESSES=4
Template
1
{{ env "NGINX_WORKER_PROCESSES" "auto" }}
Output
1
4

1
Template
1
{{ env "NGINX_WORKER_PROCESSES" "auto" }}
Output
1
auto

Which Should I Use?

  • Use .Env for direct access when you are certain the variable exists and want strict error handling.
  • Use the env function if you want to provide a default value or handle missing variables gracefully.

Both methods are available so you can choose the best fit for your use-case.

Combination with Functions

You can combine environment variable access with template functions for advanced processing. The examples below show how to use .Env and env together with functions like parseBool and split to transform environment variable values directly in your templates.

.Env + parseBool

1
NGINX_SSL_ENABLED=false
Template
1
{{ .Env.NGINX_SSL_ENABLED | parseBool }}
Output
1
false

1
Template
1
{{ .Env.NGINX_SSL_ENABLED | parseBool }}
Output
1
error: map has no entry for key "NGINX_SSL_ENABLED"

env + parseBool

1
NGINX_SSL_ENABLED=false
Template
1
{{ env "NGINX_SSL_ENABLED" "true" | parseBool }}
Output
1
false

1
Template
1
{{ env "NGINX_SSL_ENABLED" "true" | parseBool }}
Output
1
true

env + split

1
NGINX_GZIP_TYPES="text/html application/json"
Template
1
{{ env "NGINX_GZIP_TYPES" "text/plain text/css" | split " " }}
Output
1
[text/html application/json]

1
Template
1
{{ env "NGINX_GZIP_TYPES" "text/plain text/css" | split " " }}
Output
1
[text/plain text/css]

if + env + parseBool

You can use a if with env and parseBool to conditionally insert content based on the value of an environment variable.

1
NGINX_SSL_ENABLED=true
Template
1
2
3
{% if (env "NGINX_SSL_ENABLED" "false" | parseBool) %}
ssl_certificate {{ env "NGINX_SSL_CERT" "/etc/nginx/certs/server.crt" }};
{% endif %}
Output
1
ssl_certificate /etc/nginx/certs/server.crt;

1
Template
1
2
3
{% if (env "NGINX_SSL_ENABLED" "false" | parseBool) %}
ssl_certificate {{ env "NGINX_SSL_CERT" "/etc/nginx/certs/server.crt" }};
{% endif %}
Output
1

for + env + split

You can use a for loop with env and split to iterate over a list of values from an environment variable.

1
NGINX_ALLOWED_IPS="10.0.0.1 10.0.0.2 10.0.0.3"
Template
1
2
3
{% for ip in env "NGINX_ALLOWED_IPS" "127.0.0.1" | split " " %}
allow {{ ip }};
{% endfor %}
Output
1
2
3
allow 10.0.0.1;
allow 10.0.0.2;
allow 10.0.0.3;

1
Template
1
2
3
{% for ip in env "NGINX_ALLOWED_IPS" "127.0.0.1" | split " " %}
allow {{ ip }};
{% endfor %}
Output
1
allow 127.0.0.1;

Tip

For a full list of available variables, see the Variables page.

Tip

For a full list of available functions, see the Functions page.