Adding custom environment variables
About environment variables
Environment variables contain a name and value, and provide a simple way to share configuration settings between multiple applications and processes in Linux.
For example, Cloud 66 creates environment variables for your database server address, which can be referenced in your code. This has numerous benefits:
- Makes it easy to handle the fact that your environments use different environment-specific configurations
- These values may change, so setting them as variables reduces the need for code changes
- You avoid having to commit sensitive information to your Git repository
Auto-generate variables
AUTO_GENERATE environment variables allow you to insert a generic environment variable into your application, and Cloud 66 will automatically replace their value with a random string. This is useful to have Cloud 66 automatically generate values for secrets that you do not want to have commited into your repository.
To use AUTO_GENERATE environment variables, you define any environment variables with the value AUTO_GENERATE or AUTO_GENERATE_{number} - where number is the length of the value to auto-generate - i.e. AUTO_GENERATE_32.
If you use these values, then Cloud 66 will replace them with a fixed random string of the specified length (10 is the default length). Using this, you can safely commit your env file to your git repository with the following content for example, then load it when you create your new application for concrete values.
Default env-vars
As mentioned earlier, Cloud 66 auto-generates a number of environment variables, which can be used in addition to those that you define. Depending on your application configuration, the environment variables available will differ.
The following variables are created for Rack-based applications (among others):
- RAILS_ENV — Your Rails environment
- RACK_ENV — Your Rack environment
- STACK_PATH — The directory path to which your code is deployed
For database servers that we manage, we automatically create variables and insert them into your database.yml
and/or mongoid.yml
. For example, for a MySQL database we would create variables such as:
- MYSQL_ADDRESS — The physical address of your server
- MYSQL_USERNAME — Randomly generated string
- MYSQL_PASSWORD — Randomly generated string
- MYSQL_DATABASE — the name of the database
If your application uses an externally hosted (self-managed) database, we will not generate any of these variables. If your config files rely on environment variables, you will need to set these manually before you deploy, or we will not be able to connect to your database. Please read our database management guide for more details.
For a full list of environment variables available in your application, visit the Environment variables link in the right sidebar of your Application Overview. If you don’t currently have an application, the environment variables available to you are shown after your code analysis.
Assign env-vars for deployment
When you create a new application, you are given the option to assign your own environment variables after code analysis. Once your code has been analyzed, click Add environment variables before deployment in the About your app field. This will allow you to view the environment variables that Cloud 66 sets for you, and set your own.
You can set your own by either manually entering them, or uploading a file that contain the variables. This file should use the following format:
KEY_1=value_1
KEY_2=value_2
If your application relies on specific environment variables to complete the deployment process, it is worth adding them before deploying.
Assign env-vars after app build
You can also set environment variables on an existing application by visiting the Environment variables link in the right sidebar of your Application Overview. Once you click Save, these variables will be propagated to all your servers automatically, ready for your use.
Be aware of the following while assigning environment variables:
Environment variables are not escaped
However, they are always wrapped in double quotes (e.g. “ENV_VAR” ) so you can use them with multi-line variables like SSH keys.
Some environment variables cannot be modified
For example, environment variables for your server IP addresses cannot be changed because they are automatically set and updated based on reported IP addresses.
Managing environment variables using Toolbelt
You can also manage your environment variables using your Cloud 66 Toolbelt. There are four methods for managing env vars via Toolbelt:
- Listing environment variables
- Downloading variables as a file
- Setting individual variables
- Setting variables in bulk by uploading a file
Please click on the links above for detailed instructions on each of these methods.
Referencing environment variables
You can define a new environment variable and reference it to an existing environment variable on the same application, or between different applications.
Creating a reference can be done using {{ENV_VAR}}
or _env(ENV_VAR:DEFAULT_VALUE)
syntax.
The second form is useful when you want to specify a default value. If cloud66 can’t find referenced environment variable it will use default value instead. DEFAULT_VALUE is optional.
MY_HEALTH_CHECK=http://_env(WEB_ADDRESS_EXT)/health_check.html
If you are not using prefix/suffix in environment variable definition, you can use
_env:(ENV_VAR:DEFAULT_VALUE)
syntax
MY_KEY_1=_env(WEB_ADDRESS_EXT:192.168.0.1)
Referencing env vars in manifest files
You can add environment variables to your manifest files, either globally or per environment. Read our manifest guide for more details.
Referencing other env vars on the same app
This is useful when referencing an environment variable which you don’t control such as a server IP address. To do this you can use:
{{ENV_VAR}}
OR_env(ENV_VAR:DEFAULT_VALUE)
Referencing env vars on other apps
To reference to an environment variable on other applications you can use:
{{APP[APP_UID].ENV_VAR}}
OR_env(APP[APP_UID].ENV_VAR)
.
You need administrative privileges on the target application to reference environment variables on it. You cannot use intra-application environment variables to gain access to database credentials, only database addresses.
Using environment variables
Using environment variables is done differently depending on your application settings, but these are some examples.
- Bash scripts
$ENV_VAR
- .YML files
username: <%= ENV['DB_USER'] %>
- .RB files
working_directory "#{ENV['APP_PATH']}"
Pre-defined environment variables
There are some variables that are predefined by Cloud66 which are listed at bellow.
SERVER_NAME: Is on each server and is only available inside the server
What’s next?
- Learn how to use Manifest files to customize the components of your application
- Learn how to use CustomConfig - a powerful tool for configuring the components of your application.
- Learn how to customize your deployment workflow with deploy hooks.