Environment Variables

Last Updated February 2015

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

Video Overview

Defining Custom Environment Variables

Environment Variables can be defined in either the Dashboard, your Boxfile, or through the Pagoda CLI.

Naming Restrictions

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
/Boxfile

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:

Create an Environment Variable
List an App's Environment Variables
Remove an Environment Variable

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>

Examples:

DATABASE1_USER
DATABASE1_PASS
DATABASE1_NAME
DATABASE1_HOST
DATABASE1_PORT

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']);
/Boxfile

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 MAP:.

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'
/Boxfile

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
/Boxfile

With this Boxfile, Symfony should be able to connect to the database after the first deploy.

If you have any questions, suggestions, or corrections, let us know.