Configuration

# Environment variables

Clear and secret environment variables, shared or scoped per role.

Environment variables can be set directly in the dash configuration or read from `.dash/secrets`.

## Reading environment variables from the configuration

Environment variables can be set directly in the configuration file.

These are passed to the `docker run` command when deploying.

```yaml
env:
  DATABASE_HOST: mysql-db1
  DATABASE_PORT: 3306
```

## Secrets

dash uses dotenv to automatically load environment variables from the configured secrets files.

Common secrets across all destinations can be set in `.dash/secrets-common`. dash looks for `.dash/secrets-common` first, then `.dash/secrets`, with later values overriding earlier ones.

If you are using destinations, dash looks for `.dash/secrets-common` first, then `.dash/secrets.<destination>`. The non-destination `.dash/secrets` file is not read when a destination is selected.

This file can be used to set variables like `DASH_REGISTRY_PASSWORD` or database passwords. You can use variable or command substitution in the secrets file.

```shell
DASH_REGISTRY_PASSWORD=$DASH_REGISTRY_PASSWORD
RAILS_MASTER_KEY=$(cat config/master.key)
```

You can also use [secret helpers](https://dash.zoolutions.llc/docs/secrets) for common password managers and secret stores.

```shell
SECRETS=$(dash secrets fetch ...)

REGISTRY_PASSWORD=$(dash secrets extract REGISTRY_PASSWORD $SECRETS)
DB_PASSWORD=$(dash secrets extract DB_PASSWORD $SECRETS)
```

If you store secrets directly in `.dash/secrets`, ensure that it is not checked into version control.

To pass the secrets, you should list them under the `secret` key. When you do this, the other variables need to be moved under the `clear` key.

Unlike clear values, secrets are not passed directly to the container but are stored in an env file on the host:

```yaml
env:
  clear:
    DB_USER: app
  secret:
    - DB_PASSWORD
```

## Aliased secrets

You can also alias secrets to other secrets using a `:` separator.

This is useful when the ENV name is different from the secret name. For example, if you have two places where you need to define the ENV variable `DB_PASSWORD`, but the value is different depending on the context.

```shell
SECRETS=$(dash secrets fetch ...)

MAIN_DB_PASSWORD=$(dash secrets extract MAIN_DB_PASSWORD $SECRETS)
SECONDARY_DB_PASSWORD=$(dash secrets extract SECONDARY_DB_PASSWORD $SECRETS)
```

```yaml
env:
  secret:
    - DB_PASSWORD:MAIN_DB_PASSWORD
  tags:
    secondary_db:
      secret:
        - DB_PASSWORD:SECONDARY_DB_PASSWORD
accessories:
  main_db_accessory:
    env:
      secret:
        - DB_PASSWORD:MAIN_DB_PASSWORD
  secondary_db_accessory:
    env:
      secret:
        - DB_PASSWORD:SECONDARY_DB_PASSWORD
```

## Tags

Tags are used to add extra env variables to specific hosts. See dash docs servers for how to tag hosts.

Tags are only allowed in the top-level env configuration (i.e., not under a role-specific env).

The env variables can be specified with secret and clear values as explained above.

```yaml
env:
  tags:
    <tag1>:
      MYSQL_USER: monitoring
    <tag2>:
      clear:
        MYSQL_USER: readonly
      secret:
        - MYSQL_PASSWORD
```

Example configuration

```yaml
env:
  clear:
    MYSQL_USER: app
  secret:
    - MYSQL_PASSWORD
  tags:
    monitoring:
      MYSQL_USER: monitoring
    replica:
      clear:
        MYSQL_USER: readonly
      secret:
        - READONLY_PASSWORD
```

> **Note:** Generated from the gem's `lib/dash/configuration/docs/env.yml` — the same reference `dash docs env` prints in your terminal, so this page always matches your installed version.