Environment Variables

Environment variables for your application, workers, and cronjobs are defined under the env key. The keys you provide are the names of the environment variables.

Variables can be defined in two primary ways: either as a direct string value for basic usage, or as an object for more advanced configurations that allow control over aspects like build-time availability or mounting as files. It is also valid to define a basic variable using the object structure with only the value key specified.

Basic Usage (String Value)

The simplest way to define an environment variable is by providing its name as the key and a string as the value.

env:
  APP_ENV: production
  LOG_CHANNEL: stack

Alternatively, you can define a basic variable using an object with just the value key. This is functionally identical to the string format:

env:
  DATABASE_HOST:
    value: "mariadb-p-123.db.ondigitalocean.com"

Advanced Configuration (Object Value)

For scenarios requiring more control, such as making variables available only during build-time or mounting their content as files, you must use the object format.

env:
  MY_VARIABLE:
    value: "my-value"
    build: false
    file: "my-variable.txt"

This structure explains the two ways to define a variable.

Key	Description	Default
`value`	The literal value of the environment variable.	(required)
`build`	(Optional) Controls availability in the GitLab CI/CD pipeline. If `true`, it's available at build-time and run-time. If `'only'`, it is only available at build-time.	`false`
`file`	(Optional) A string representing a filename. The value will be mounted as a file with this name inside a system-defined secrets directory. The environment variable will then hold the full path to this file instead of the value itself.	`null`

Example: Build-time Variable

This variable will be available during the build stage in GitLab CI/CD, but not in the final running container.

env:
  ASSET_COMPILATION_FLAG:
    value: "true"
    build: only

Example: Variable as a File

This is useful for long configuration strings or multi-line values. The APP_SERVICE_ACCOUNT_JSON environment variable will be set to the absolute path of the created file.

env:
  APP_SERVICE_ACCOUNT_JSON:
    value: '{"type": "service_account", ...}'
    file: google-creds.json

Using GitLab CI/CD Secrets

You can securely inject secrets defined in your GitLab project's CI/CD settings (Settings > CI/CD > Variables). To do this, use the gitlab key instead of value.

Specifying the Secret Name

You can specify the name of the secret from GitLab in two ways:

1. As a string:

env:
  MY_SECRET_KEY:
    gitlab: "NAME_OF_SECRET_IN_GITLAB"

2. As an object with a name property:

env:
  MY_SECRET_KEY:
    gitlab:
      name: "NAME_OF_SECRET_IN_GITLAB"

Implicit Secret Name

If you define the gitlab key but leave it null (~) or omit the name property, the name of your environment variable itself will be used to look up the secret in GitLab.

This is useful for maintaining consistency between your cap config file and GitLab CI/CD variables.

env:
  # This will look for a GitLab secret named "API_KEY"
  API_KEY:
    gitlab: ~

  # This will also look for a GitLab secret named "ANOTHER_SECRET"
  ANOTHER_SECRET:
    gitlab: {}

GitLab Secrets as Files

You can also mount GitLab secrets as files by providing the file property with a filename.

env:
  SSH_PRIVATE_KEY:
    # Looks for a GitLab secret named "CI_SSH_PRIVATE_KEY"
    gitlab: "CI_SSH_PRIVATE_KEY"
    # The SSH_PRIVATE_KEY env var will contain the absolute path to the secret file
    file: id_rsa

Connection String Templating

For dynamic values that depend on the services you've defined, you can use connection string templating. This allows you to reference properties of your services, like hostnames, ports, and credentials, without hardcoding them.

The template syntax uses double curly braces: {{ path.to.variable }}.

Example

If you have a MariaDB service named db, you can construct a database URL like this:

env:
  DATABASE_URL:
    value: "mariadb://{{ svc.db.conn.default.username }}:{{ svc.db.conn.default.password }}@{{ svc.db.conn.default.hostname }}:{{ svc.db.conn.default.port }}/{{ svc.db.conn.default.database }}"

This will be automatically resolved to the correct connection string for your db service.

Available Variables

The following variables are available for templating.

Global Variables (`cap`)

Variable	Description
`cap.application`	The name of the application.
`cap.environment`	The deployment environment (e.g., `production`, `staging`).
`cap.instance`	The instance name.
`cap.cluster`	The name of the cluster. (e.g., `production`, `shared`).
`cap.hostname`	The application's primary hostname.

Service Variables (`svc`)

Service variables are accessed under svc.<service_name>.conn.<connection_name>. In most cases, <connection_name> is default.

MariaDB, PostgreSQL, CockroachDB

Property	Example
`hostname`	`{{ svc.db.conn.default.hostname }}`
`port`	`{{ svc.db.conn.default.port }}`
`username`	`{{ svc.db.conn.default.username }}`
`password`	`{{ svc.db.conn.default.password }}`
`database`	`{{ svc.db.conn.default.database }}`
`version`	`{{ svc.db.conn.default.version }}`

RabbitMQ

Property	Example
`hostname`	`{{ svc.queue.conn.default.hostname }}`
`port`	`{{ svc.queue.conn.default.port }}`
`username`	`{{ svc.queue.conn.default.username }}`
`password`	`{{ svc.queue.conn.default.password }}`
`vhost`	`{{ svc.queue.conn.default.vhost }}`
`version`	`{{ svc.queue.conn.default.version }}`

Dragonfly

Property	Example
`hostname`	`{{ svc.cache.conn.default.hostname }}`
`port`	`{{ svc.cache.conn.default.port }}`
`database`	`{{ svc.cache.conn.default.database }}`
`version`	`{{ svc.cache.conn.default.version }}`