Using Environment Variables

OpenShift has several environment variables to make it easy for your to configure your application to run properly.

Introduction

Environment variables are placeholders for values that are provided to a software program at runtime. They are particularly useful when the values are likely to be different from one host system to the next, or from one run to the next. Including these placeholders in applications makes the application code more portable and flexible. This flexibility is critical for writing applications that are easily deployed and scaled on OpenShift Online.

A number of standardized environment variables are available for applications hosted on OpenShift Online. These variables serve as placeholders for application names, commonly accessed directory names, user names, passwords, host names, IP addresses, and more. The specific environment variables that are available to a given application is determined by the cartridges that have been added to that application. For example, an application with PHP and MySQL has access to environment variables that expose the PHP path information, including the host, port, user name, and password necessary for connecting to the MySQL database.

There are two ways to view the environment variables for an application:

  1. Add an export statement to the App_Name/.openshift/action_hooks/build file, then run git push. The variables are listed in the Git output and start with remote: declare -x.

  2. Access the application with SSH and run the env command at the shell prompt.

Informational Environment Variables

Informational environment variables provide information about an application. These variables are always available to the application, regardless of which cartridges the application is using.

Variable Name

Purpose

OPENSHIFT_APP_DNS

The fully-qualified domain namespace of the application.

OPENSHIFT_APP_NAME

The name of the application.

OPENSHIFT_APP_UUID

The UUID of the application (32 hexadecimal characters).

OPENSHIFT_<cart-name>_IP

The IP address the application listens on.

OPENSHIFT_<cart-name>_PORT

The port the application receives requests from.

OPENSHIFT_SECRET_TOKEN

A 128-character string unique to an application that can be used for authentication, and can be overridden with the rhc env set command.

The exact variable names depend on the type of cartridge; the value of <cart-name> is DIY, JBOSSAS, JBOSSEAP, JBOSSEWS, JENKINS, MONGODB, MYSQL, NODEJS, PERL, PHP, POSTGRESQL, PYTHON, or RUBY as appropriate.

Directory Environment Variables

Directory environment variables return the directories where an application resides. These variables are always available to the application, regardless of which cartridges the application is using.

Variable Name

Purpose

OPENSHIFT_HOMEDIR

The home directory of the application.

OPENSHIFT_DATA_DIR

A persistent data directory.

OPENSHIFT_REPO_DIR

Repository containing the currently deployed version of the application.

OPENSHIFT_TMP_DIR

A temporary directory you can use; SELinux protects data in this directory from other users.

OPENSHIFT_LOG_DIR

Where all cartridge logs are stored.

Many of these directories are emptied and rebuilt whenever new code is pushed to an application. The only persistent directory is OPENSHIFT_DATA_DIR. Therefore, Red Hat recommends that you store persistent files in the OPENSHIFT_DATA_DIR directory.

Logging Environment Variables

Logging environment variables are available to configure the behavior of logs generated by an application. When logs are written to the OPENSHIFT_LOG_DIR directory of an application, log files are rolled if their file size exceeds a configurable threshold. A configurable number of rolled files are retained before the oldest file is removed prior to the next roll.

Variable Name

Purpose

LOGSHIFTER_<cart-name>_MAX_FILESIZE

A case-insensitive string representing the maximum log file size that triggers a roll event. The default value is 10M. If a zero size is specified regardless of the unit, log rolling is effectively disabled.

LOGSHIFTER_<cart-name>_MAX_FILES

An integer representing the maximum number of log files to retain. The default is 10.

The exact variable names depend on the type of cartridge; the value of <cart-name> is DIY, JBOSSAS, JBOSSEAP, JBOSSEWS, JENKINS, MONGODB, MYSQL, NODEJS, PERL, PHP, POSTGRESQL, PYTHON, or RUBY as appropriate.

The LOGSHIFTER_<cart-name>_MAX_FILESIZE variable accepts strings in kilobytes, megabytes, gigabytes, and terabytes. For example, for an application with a PHP cartridge, any of the following values would be valid:

  • LOGSHIFTER_PHP_MAX_FILESIZE=500K

  • LOGSHIFTER_PHP_MAX_FILESIZE=10M

  • LOGSHIFTER_PHP_MAX_FILESIZE=2G

  • LOGSHIFTER_PHP_MAX_FILESIZE=1T

Database Environment Variables

Database environment variables pertain to a database, if one exists, and are used to connect an application to a database. Note that these connections are only available to an application internally; you cannot connect from an external source.

OpenShift Online does not currently support user changes to environment variables. This includes changing the default MySQL admin password (even outside of phpMyAdmin). If the password is changed, ensure the change takes effect correctly. Note that this restriction only applies to the default administrative user. You can add more users as required, and specify a custom password for these users.

Variable Name

Purpose

OPENSHIFT_<database>_DB_HOST

The host name or IP address used to connect to the database.

OPENSHIFT_<database>_DB_PORT

The port the database server is listening on.

OPENSHIFT_<database>_DB_USERNAME

The database administrative user name.

OPENSHIFT_<database>_DB_PASSWORD

The database administrative user’s password.

OPENSHIFT_<database>_DB_SOCKET

An AF socket for connecting to the database (for non-scaled apps only).

OPENSHIFT_<database>_DB_URL

Database connection URL.

The exact variable names depend on the type of database; the value of <database> is MONGODB, MYSQL, or POSTGRESQL as appropriate.

Library Environment Variables

Library environment variables are used for customizing the location of bundled files.

Variable Name

Purpose

OPENSHIFT_<cart-name>_LD_LIBRARY_PATH_ELEMENT

Configures the location of each cartridge’s library file.

The exact variable names depend on the type of cartridge; the value of <cart-name> is DIY, JBOSSAS, JBOSSEAP, JBOSSEWS, JENKINS, MONGODB, MYSQL, NODEJS, PERL, PHP, POSTGRESQL, PYTHON, or RUBY as appropriate.
The global directory for a cartridge is set with LD_LIBRARY_PATH. However, cartridges may be competing for a place in the set directory. Configure the destination of each cartridge’s files with OPENSHIFT_<cart-name>_LD_LIBRARY_PATH_ELEMENT to merge each cartridge’s library into the global directory. Note that the order that the files are entered into the global directory is add-on cartridges first, then web framework cartridges. Red Hat recommends not changing the location of the LD_LIBRARY_PATH environment variable.

Jenkins Environment Variables

Jenkins environment variables are available if an application has Jenkins enabled.

Variable Name

Purpose

JENKINS_USERNAME

System builder account on the Jenkins server.

JENKINS_PASSWORD

Password for the system builder account on the Jenkins server.

JENKINS_URL

DNS name for the associated Jenkins server where builds occur.

Java Environment Variables

Java environment variables are available if an application has a Java cartridge installed.

Variable Name

Purpose

JAVA_OPTS_EXT

Appended to JAVA_OPTS prior to invoking the Java VM.

Gear Environment Variables

These variables will be used if you have a scaling application.

Variable Name

Purpose

OPENSHIFT_GEAR_DNS

The fully-qualified domain name of the gear.

OPENSHIFT_GEAR_NAME

The name of the gear.

OPENSHIFT_GEAR_UUID

The UUID of the gear.

Custom Environment Variables

Custom environment variables are user defined to use with applications.

Setting Custom Environment Variables

Set one of more environment variables for an application with the following command:

$ rhc env set <Variable>=<Value> <Variable2>=<Value2> -a App_Name

Add additional <Variable>=<Value> arguments separated by spaces to set multiple variables.

Viewing Custom Environment Variables

View the custom environment variables set for an application with the following command:

$ rhc env list -a App_Name

Viewing the Value of a Custom Environment Variable

Display the value of one or more custom environment variables with the following command:

$ rhc env show <Variable> <Variable2> -a App_Name

Removing Custom Environment Variables

Remove a custom environment variable with the following command:

$ rhc env unset <Variable> -a App_Name

Reading Environment Variables: Examples

The following table shows an example of how to read an environment variable for each of the fully-supported languages on OpenShift.

Language Example

Java

String envVar = System.getenv("OPENSHIFT_ENV_VAR");

JavaScript

var envVar = process.env.OPENSHIFT_ENV_VAR;

Perl

$envVar = $ENV{'OPENSHIFT_ENV_VAR'};

PHP

$env_var = getenv('OPENSHIFT_ENV_VAR');

Python

env_var = os.environ['OPENSHIFT_ENV_VAR']

Ruby

:env_var => ENV['OPENSHIFT_ENV_VAR']

Node.js

process.env.OPENSHIFT_ENV_VAR