Environment variables

This page lists every environment variable the dockflow CLI and its installer read, grouped by use. The last section lists the built-in variables Dockflow gives to your Compose files, templates and hooks.

Dockflow reads nothing else from the environment: PATH, HOME and the rest of your variables never become secrets.

SecretsCopy Anchor Link

For an environment named production, a key X is looked up as PRODUCTION_X, then X, in each source in turn. The first match wins. The full lookup order, with vars and the built-in variables, is in the dockflow.yml reference.

The sources, in priority order:

1. the process variables prefixed with the environment's name, and the keys of DOCKFLOW_SECRETS;
2. .env.dockflow at the project root;
3. the environment's SOPS file, when there is one.

      - run: dockflow deploy
        env:
          DOCKFLOW_SECRETS: ${{ toJSON(secrets) }}

.env.dockflowCopy Anchor Link

A KEY=value file at the project root, for local use. Keep it out of git.

PRODUCTION_CONNECTION=eyJ2IjoyLCJzZXJ2ZXJzIjpb...
DB_PASSWORD='p@ss$word'
export API_KEY="line one\nline two"

• Blank lines and lines starting with # are ignored; a leading export is allowed.
• Values are taken literally: $ is never expanded.
• Single or double quotes around a value are removed. Inside double quotes, \n, \t, \" and \\ are understood.
• In an unquoted value, # starts a comment.

Secrets override the environment's vars of the same name. Their values are masked as *** in everything Dockflow prints. See Configuration for where they can be used.

Connecting to the serverCopy Anchor Link

When the server comes from dockflow.yml, Dockflow picks the private key in this order:

1. the key in DOCKFLOW_SSH_KEY_<ENV>;
2. the key in DOCKFLOW_SSH_KEY;
3. the keys of ssh-agent;
4. the IdentityFile keys ~/.ssh/config gives the host or, when it gives none, the files ~/.ssh/id_ed25519, ~/.ssh/id_ecdsa and ~/.ssh/id_rsa.

A key protected by a passphrase must be loaded in ssh-agent. The host key is checked against host_key: or ~/.ssh/known_hosts.

The agent binaryCopy Anchor Link

The CLI starts the agent on the server, which runs a Linux binary of exactly the CLI's version. When the CLI is not that binary (on macOS, on Windows, or on a different architecture), it downloads it from the release. It checks the download against the checksum the CLI was built with, and caches it in your user cache directory (~/.cache/dockflow/<version>/ on Linux).

OutputCopy Anchor Link

Other commandsCopy Anchor Link

CI detectionCopy Anchor Link

In CI, Dockflow reads the provider's variables to know the tag or branch, the commit and who started the run.

• A tag selects the environment and the version label of deploy and build.
• The branch and commit fill DOCKFLOW_GIT_BRANCH and DOCKFLOW_GIT_SHA when the checkout does not have them (a detached or shallow clone).
• The provider and the person are recorded in the release.

The providers are checked in this order; the first that matches is used. Outside CI, the release records USER (or the current system user) and the machine's host name.

BuildsCopy Anchor Link

Local builds run docker buildx (or podman with build.engine: podman) with your environment. The usual Docker variables, such as DOCKER_HOST, DOCKER_CONTEXT and BUILDX_BUILDER, apply to them.

Remote builds (build.builder: remote) set DOCKER_HOST to a local socket forwarded to the server's Docker, and clear DOCKER_CONTEXT and BUILDX_BUILDER. This applies to the build command only.

Temporary files go to the system's temporary directory (TMPDIR).

InstallerCopy Anchor Link

install.sh reads these variables, equivalent to its options:

curl -fsSL https://raw.githubusercontent.com/Shawiizz/dockflow/main/install.sh | DOCKFLOW_VERSION=v1.0.0-alpha.6 sh

Built-in variablesCopy Anchor Link

Dockflow defines these variables for every environment. They come first in the lookup, before secrets and vars, so neither a secret nor a var can override them.

Where they are available:

services:
  web:
    image: nginx:1.27
    environment:
      APP_ENV: ${DOCKFLOW_ENV}
    labels:
      com.example.stack: ${DOCKFLOW_STACK}

They are not added to your containers' environment on their own: a container sees one only when your Compose file puts it there.