On this page

Environment variables

Clever Cloud allows you to define environment variables that will be injected in your application’s environment.

How are variables defined?

Variables are defined on a per-application basis. They are defined in four ways:

  • By provisioned add-ons linked to applications. The variables names are listed in the add-on’s information panel

  • By linked applications with exposed configuration

  • By adding variables yourself in the “Environment variables” panel of your application.

  • Some environment variables are added automatically for each application.

Please note that if you define or modify environment variables, you will need to redeploy your application to make it use the new variables.

Check out our environment variable reference.

Special environment variables

Some variables are injected to the environment of your application when you deploy it, to inform you about the current context of your application and about the application itself.

They can be accessed as classic environment variables.

  • APP_ID: the ID of the application. Each application has a unique identifier used to identify it in our system. This ID is the same than the one you can find in the information section of your application.

  • INSTANCE_ID: the ID of the current instance (scaler) of your application. It’s unique for each instance of your application and changes every time you deploy it.

  • INSTANCE_TYPE: The type of the instance (scaler). Its value can be build or production. build is when your application is being built on a dedicated instance.

  • COMMIT_ID: the commit ID used as a base to deploy your application. As we remove the .git directory before the deployment (to avoid security problems), it can be used to know which version of your application is running on the server.

  • APP_HOME: The absolute path of your application on the server. Can be used to create absolute links in your application (e.g. ${APP_HOME}/foo/bar).

  • CC_PRETTY_INSTANCE_NAME: A random string name generated for each instance using pokemon names.

  • INSTANCE_NUMBER: See below

What is the INSTANCE_NUMBER variable used for?

This variable allows your application to differentiate each running node on the application level.

It will contain a different number for each instance of your application.

For example, if three instances are running, it will contain 0 for the first, 1 for the second and 2 for the third. It’s handy if you want to only run crons on 1 instance (e.g. only on instance 0)

Settings you can define using environment variables

We use environment variables for some settings:

  • IGNORE_FROM_BUILDCACHE: allows you to specify paths to ignore when the build cache archive is created. Must be relative to your application root. (ex: foo/bar:foo/baz where bar or baz can be either a folder or a file)

  • CC_OVERRIDE_BUILDCACHE: allows you to specify paths that will be in the build cache. Only those files / directories will be cached. (ex: foo/bar:foo/baz where bar or baz can be either a folder or a file)

Environment variables rules and formats

You will find below a list of rules applied to our environment variables keys and examples of the formats available on our different modes.

Rules

  • Letters (ASCII only, upper and lower case)
    • Valid:
      • user_id
      • USER_ID
      • UsERId
      • userid
      • USERID
    • Not Valid:
      • user_id?
      • ?userid
      • user.id
      • user id
  • Digits (but not for first character)
    • Valid:
      • user2id
      • userid42
    • Not Valid:
      • 2userid
      • 1user_Id
  • Underscores
    • Valid:
      • user_id
      • all_user_id
      • _user_id
      • _user_id__
  • Everything else is not allowed

Java properties rules exception

In case of a Java application you can also use:

  • Dashes
    • Valid:
      • spring-boot
      • spring-boot-database
      • --spring-boot
      • --spring
  • Dots
    • Valid:
      • spring.boot
      • spring.datasource.url
      • .spring.url

Format

Here are some formats that you can use when changing your variables on our expert and JSON mode. Note: For each mode you can obviously have multiple environment variables.

Expert

The format of an expert variable is: VAR_NAME="VALUE"

Here are some examples for the mode:

  • Multiple variables examples:
EMPTY=""
MULTI="line one
line two
line three"
ONE="value ONE"
TWO="value TWO"
  • Multiline:
MULTI="line one
line two
line three"
  • Empty value:
EMPTY=""

JSON

The format of a JSON variable is: { "name": "THE_NAME", "value": "the value" }. Note: You must put these variables in an array (see the multiple variable example to see how it goes).

Here are some examples for the mode:

  • Multiline:
{
  "name": "MULTI",
  "value": "line one\nline two\nline three"
}
  • Empty value:
{
  "name": "EMPTY",
  "value": ""
}
  • Multiple variables examples:
[
  {
    "name": "EMPTY",
    "value": ""
  },
  {
    "name": "MULTI",
    "value": "line one\nline two\nline three"
  },
  {
    "name": "ONE",
    "value": "value ONE"
  },
  {
    "name": "TWO",
    "value": "value TWO"
  }
]

How do I use these variables?

Depending on the type of your application, you will need to use different ways. You can find the various ways in the specific instances documentations.

Please note that the variables are available at build-time, for runtimes that support build-time instructions, such as Java WAR, Play! Framework 1, Play! Framework 2 or Scala.

Comments