Environment variables are a handy tool used in most web applications. Pagoda Box makes creating and using Environment Variables really easy. They can be used for obscuring sensitive information, simplifying multi-environment management, or any other way you can think of to use them in your app. Pagoda Box dynamically creates a number of Environment Variables that are available to your app. This doc covers how to create and use Environment Vairables and after reading it, you should be familiar with:
- Defining custom environment variables
- Auto-Generated environment variables
Defining Custom Environment Variables
Environment Variables can be defined in either the Dashboard, your Boxfile, or through the Pagoda CLI.
Environment variable names cannot include hyphens or begin with a number.
In the Dashboard
To define custom Environment Variables, go to Dev Config > Env.Vars in your app dashboard and click the "New Environment Variable" button. Variables are defined in key-value pairs. Simply enter your variable name in the “KEY” field and your variable value in the “value” field and click Save.
In the Boxfile
You can create Environment Variables in your Boxfile by including the key value pairs under the global context as show below
Environment Variables in the Boxfile YAML
global: env: - KEY: value - ENV: production
Through the Pagoda CLI
The Pagoda CLI's
evar:create command allows you to add environment variables from the command line.
Using pagoda evar:create Terminal
# Pattern $ pagoda evar:create [-a app-name] KEY=VALUE # Examples $ pagoda evar:create ENV=production
More information about this command and other commands related to environment variables are available in the Pagoda CLI doc:
Auto-Generated Environment Variables
Pagoda Box automatically generates Environment Variables for each credential in all services that require connection credentials. You can view auto-generated environment variables in your App Dashboard under Dev Config > Env. Var.
The naming convention for auto-generated environment variables is:
<Service ID>_<Four-Letter Credential Name>
This allows you to put environment variables in place of connection credentials before the service is even created. This really comes in handy when coding Quickstarts.
Using Environment Variables
Environment variables are accessed differently depending on the language you're using. For example, PHP uses the
$_SERVER array to access environment variables. Below is a simple example using the auto-generated environment variables for database1:
Using Environment Variables in PHP PHP
define('DB_NAME', $_SERVER['DATABASE1_NAME']); define('DB_USER', $_SERVER['DATABASE1_USER']); define('DB_PASSWORD', $_SERVER['DATABASE1_PASS']); define('DB_HOST', $_SERVER['DATABASE1_HOST']);
Mapping Environment Variables
Some frameworks include out-of-the-box environment variables that can be used to populate important information, such as database connection credentials. On Pagoda Box, you can "map" these environment variables to other environment variables associated with the app. In the value of your environment variable key-value pair, prepend the desired mapped environment variable with
Below are examples of how mapped variables would be added in the Boxfile and in the dashboard. The value of
MY_VARIABLE is being mapped to use the value of
APP_NAME, an auto-generated environment variable.
Environment Variable Mapping in the Boxfile YAML
global: env: - MY_VARIABLE: 'MAP:APP_NAME'
Environment Variable Maps Are a 1:1 Relationship
Mapping environment variables can only create 1:1 realationships. You cannot map an environment variable to a concatenated string of environment variables.
Symfony Use Case
The Symfony PHP framework is a perfect use case for environment variable mapping. Symphony will "grab any environment variable begginning with
SYMFONY__ and set it as a parameter in a service container" (More info here). This can be used to quickly populate database connection credentials.
Previously, Symfony users would have to deploy an app, create all the necessary services, then one by one, add all the corresponding Symfony environment variables and their values. With environment variable mapping, the value of these environment variables can be mapped to auto-generated environment variables and populated on the very first deploy.
Setting Symfony Environment Variables in the Boxfile YAML
global: env: - SYMFONY__DATABASE__NAME: "MAP:DATABASE1_NAME" - SYMFONY__DATABASE__HOST: "MAP:DATABASE1_HOST" - SYMFONY__DATABASE__PORT: "MAP:DATABASE1_PORT" - SYMFONY__DATABASE__USER: "MAP:DATABASE1_USER" - SYMFONY__DATABASE__PASSWORD: "MAP:DATABASE1_PASS" web1: name: symfony-web type: php database1: name: symfony-db type: mysql
With this Boxfile, Symfony should be able to connect to the database after the first deploy.
Table of Contents
- Naming Restrictions
- In the Dashboard
- In the Boxfile
- Environment Variables in the Boxfile
- Through the Pagoda CLI
- Using pagoda evar:create
If you have any questions, suggestions, or corrections, let us know.