We removed our free Sandbox April 25th.
You can read more on our blog.

Environment File

What is the Environment File?

When your application is built by the DotCloud platform, a file named environment.json is created in the home directory of each of your services.

This file contains a JSON-formatted dictionary with most of the configuration informations of the services in your stack. You can use it to retrieve automatically the host, port, and password, of your databases, caches, and so on.

Here is an example of an environment file:

{
   "DOTCLOUD_ENVIRONMENT": "default",
   "DOTCLOUD_DB_MYSQL_LOGIN": "root",
   "DOTCLOUD_DB_MYSQL_URL": "mysql://root:pass@7a96f954.dotcloud.com:7780",
   "DOTCLOUD_DB_MYSQL_PASSWORD": "B61J14)]U4^L}.najnyE",
   "DOTCLOUD_PROJECT": "demodcapp",
   "DOTCLOUD_SERVICE_NAME": "www",
   "DOTCLOUD_DB_MYSQL_PORT": "7780",
   "DOTCLOUD_DB_MYSQL_HOST": "7a96f954.dotcloud.com",
   "DOTCLOUD_SERVICE_ID": "0"
}

The environment file will contain the access information of database services in the same application. In the example, the MySQL database service named “db” is present.

Note

The environment variables defined in environment.json are not related to the “Unix” environment. In the future, DotCloud will mirror them in the “Unix” environment.

Reading the Environment

To read an environment variable you need to load the environment file first. Since it is a JSON file, this is very easy from any language:

PHP

<?php

     // Read the file and convert the underlying JSON dictionary into a PHP array
     $env = json_decode(file_get_contents("/home/dotcloud/environment.json"), true);

     echo "Application Name: {$env['DOTCLOUD_PROJECT']}\n";

?>

Ruby

Add the “json” requirement to your Gemfile:

source :rubygems
gem 'json'

Then use the following snippet to parse environment.json:

env = JSON.parse(File.read('/home/dotcloud/environment.json'))

puts "Application Name: #{env['DOTCLOUD_SERVICE_NAME']}"

Perl

Add the “JSON” requirement in your Makefile.PL, e.g:

use ExtUtils::MakeMaker;

WriteMakefile(
        NAME => "dummy",
        PREREQ_PM => {
           'JSON' => 0,
       },
);

Note

Adding “JSON” in the “requirements” list in your dotcloud.yml works too (but that’s DotCloud specific).

Then use the following snippet to parse environment.json:

use JSON;

open my $fh, "<", "/home/dotcloud/environment.json" or die $!;
my $data = JSON::decode_json(join '', <$fh>);

print  "Application name: $data->{DOTCLOUD_SERVICE_NAME}\n";

Python

import json

with open('/home/dotcloud/environment.json') as f:
  env = json.load(f)

print 'Application Name: {0}'.format(env['DOTCLOUD_SERVICE_NAME'])

NodeJS

var fs = require('fs');

var env = JSON.parse(fs.readFileSync('/home/dotcloud/environment.json', 'utf-8'));

console.log('Application Name: ' + env['DOTCLOUD_SERVICE_NAME']);

Adding Environment Variables

You can set your own environment variables either from dotcloud.yml or directly from the command line with the dotcloud var command.

The first approach is quite simple, just list your variables in the environment dictionary of the concerned service in dotcloud.yml:

www:
  type: python
  environment:
    MODE: production
    API: http://www.externalapi.com/v1/

This approach is good for environment variables that never change across deployments of your application and that can be stored in your code repository. But —most of the time— the environment holds variables that always change across deployments of your application and that can’t be stored in your repository. A perfect example is third parties service credentials. Also, you must push your application again to change environment variables defined in dotcloud.yml.

The dotcloud var command solves these issues by allowing you to set environment variable from the command line, once the application is running on DotCloud:

$ dotcloud var set myapp MYVAR=MYVALUE

Whereas dotcloud.yml allows you to define different environment variables for each service, dotcloud var set environment variable for the whole application. Moreover, environment variables set with dotcloud var supersede environment variables defined in dotcloud.yml.

You can set multiple variables at once:

$ dotcloud var set myapp \
    'AWS_ACCESS_KEY=IA4F0njNcmKKg3YndpOe' \
    'AWS_SECRET_KEY=Ideeghu0Ohghe7oi?Y6ogh7qui%jeiph7yai[coo'

You can list the variables you set with the list subcommand:

$ dotcloud var list myapp
AWS_SECRET_KEY=Ideeghu0Ohghe7oi?Y6ogh7qui%jeiph7yai[coo
AWS_ACCESS_KEY=IA4F0njNcmKKg3YndpOe
DOTCLOUD_ENVIRONMENT=default
DOTCLOUD_PROJECT=lopter

Note

Your environment variables keys must be alphanumeric characters only and cannot start with “DOTCLOUD_”.

Removing Environment Variables

You can remove environment variables set in dotcloud.yml by editing the file and pushing your code again.

You can remove environment variables set “at runtime” with dotcloud var with the unset subcommand:

$ dotcloud var unset myapp AWS_ACCESS_KEY

YAML Format

This document shows how to use environment.json but the environment is also available in the YAML format in the file environment.yaml.

If you think that another environment format is relevant, let us know at support@dotcloud.com.