Environment Variables#

Lagoon supports the use of environment variables, which are commonly used by applications to store configuration separate from code. There are multiple methods to set an env var and each Lagoon environment can have separate values.

Environment Variables (Lagoon API)#

Use Lagoon API env vars for config that you don't want to keep in your Git repository (like secrets or API keys). This prevents sensitive information from getting leaked due to accidental exposure of the code.

Env vars can be added via the Lagoon dashboard, the Lagoon CLI, or the Lagoon API.

Warning

Adding or changing API env vars won't be reflected in a Lagoon environment until the next deployment.

Env vars have a name, value, type, and scope. The type and scope determine when and where the env vars are added to Lagoon environments.

Types#

Types are used to set env vars for a set of environments. An env var can be of type organization, project, or environment. Review the precedence of all env vars to see how they interact with other types and methods.

Organization#

Organization env vars are set for all environments, in all projects, in an organization. They can be overridden by project and environment env vars.

An example of setting an organization env var:

Lagoon CLILagoon API

lagoon add variable --organization-name lagoon-demo-org --scope runtime \
--name SSMTP_MAILHUB --value mailhub.example.com

mutation {
  addOrUpdateEnvVariableByName(
    input: {
      organization: "lagoon-demo-org"
      scope: RUNTIME
      name: "SSMTP_MAILHUB"
      value: "mailhub.example.com"
    }
  ) {
    id
    name
    scope
    value
  }
}

Project#

Project env vars are set for all environments in a project. They can be overridden by environment env vars.

An example of setting a project env var:

Lagoon CLILagoon API

lagoon add variable --project lagoon-demo --scope runtime \
--name PHP_MEMORY_LIMIT --value 400M

mutation {
  addOrUpdateEnvVariableByName(
    input: {
      project: "lagoon-demo"
      scope: RUNTIME
      name: "PHP_MEMORY_LIMIT"
      value: "400M"
    }
  ) {
    id
    name
    scope
    value
  }
}

Environment#

Environment env vars are set for a single Lagoon environment.

An example of setting an environment env var:

Lagoon CLILagoon API

lagoon add variable --project lagoon-demo --environment dev \
--scope runtime --name LOG_LEVEL --value DEBUG

mutation {
  addOrUpdateEnvVariableByName(
    input: {
      project: "lagoon-demo"
      environment: "dev
      scope: RUNTIME
      name: "LOG_LEVEL"
      value: "DEBUG"
    }
  ) {
    id
    name
    scope
    value
  }
}

Scopes#

Scopes are used to set an env var for a specific context. An env var can have a scope of build, runtime, global, container_registry or internal_container_registry.

Buildtime#

Buildtime env vars are only available during Docker image builds, and can be accessed by using the ARG instruction. Check the Docker documention on ARG for all the ways to use this method.

Typically the ARG will go after the FROM. Read the Docker documentation about ARG and FROM.

An example of setting a build env var:

Lagoon CLILagoon API

lagoon add variable --project lagoon-demo --scope build \
--name COMPOSER_MEMORY_LIMIT --value -1

mutation {
  addOrUpdateEnvVariableByName(
    input: {
      project: "lagoon-demo"
      scope: BUILD
      name: "COMPOSER_MEMORY_LIMIT"
      value: "-1"
    }
  ) {
    id
    name
    scope
    value
  }
}

Runtime#

Runtime env vars are injected into all containers when they start.

An example of setting a runtime scoped env var:

Lagoon CLILagoon API

lagoon add variable --project lagoon-demo --environment dev \
--scope runtime --name LOG_LEVEL --value DEBUG

mutation {
  addOrUpdateEnvVariableByName(
    input: {
      project: "lagoon-demo"
      environment: "dev
      scope: RUNTIME
      name: "LOG_LEVEL"
      value: "DEBUG"
    }
  ) {
    id
    name
    scope
    value
  }
}

Global#

Global env vars are set at buildtime and runtime and follow the same rules as those scopes.

An example of setting a global scoped env var:

Lagoon CLILagoon API

lagoon add variable --project lagoon-demo --scope global \
--name JAVA_OPTS --value '-Xmx512m'

mutation {
  addOrUpdateEnvVariableByName(
    input: {
      project: "lagoon-demo"
      scope: GLOBAL
      name: "JAVA_OPTS"
      value: "-Xmx512m"
    }
  ) {
    id
    name
    scope
    value
  }
}

Container Registry#

Container registry scoped env vars can be used to authenticate to a private container registry so that Lagoon can pull custom and/or private images at buildtime. Check the full documentation on container registries for more information.

Warning

The scope internal_container_registry is not for general use, and shouldn't be used unless explicitly required.

An example of setting a container_registry scoped env var:

Lagoon CLILagoon API

lagoon add variable --project lagoon-demo --scope container_registry \
--name REGISTRY_DOCKERHUB_USERNAME --value dockerhub_user_123

mutation {
  addOrUpdateEnvVariableByName(
    input: {
      project: "lagoon-demo"
      scope: GLOBAL
      name: "JAVA_OPTS"
      value: "-Xmx512m"
    }
  ) {
    id
    name
    scope
    value
  }
}

Environment Files (committed to Git Repo)#

Use environment files for config that can be safely committed to a Git repository.

Environment files are only read by containers based on the Lagoon commons base image. They aren't read by Lagoon, but by the containers ENTRYPOINT scripts, which looks for them in the containers working directory. This means that these env vars are only available at runtime.

Info

If environment files aren't loading, confirm that you're using Lagoon base images, that you're copying them into the contianer as part of your Dockerfile, and that your container has a WORKDIR setting that points to the location of these files.

The syntax of an environment file is ENV_VAR_NAME="env var value":

.env

PHP_MEMORY_LIMIT="400M"
PHP_MAX_EXECUTION_TIME=900
DB_USER=$DB_USERNAME # Redefine DB_USER with the value of DB_USERNAME e.g. if your application expects another variable name for the Lagoon-provided variables.

`.lagoon.env` and `.lagoon.env.BRANCHNAME`#

Use .lagoon.env when you want to always set env vars, but only for Lagoon images.

Use .lagoon.env.BRANCHNAME when you want to set different env vars per environment. BRANCHNAME will be replaced by the env vars $LAGOON_GIT_BRANCH or $LAGOON_GIT_SAFE_BRANCH. For example, if you deployed the branch main, the file name would be .lagoon.env.main. Branch names that contain special characters are sanitized, so check the value of $LAGOON_GIT_SAFE_BRANCH to determine what the filename should be.

`.env` and `.env.defaults`#

Use .env and .env.defaults when you want to always set env vars, including for local development and non-Lagoon tools that also read them.

Docker Environment Variables#

Docker Images#

Env vars can be set in docker images by using the ENV command in your Dockerfile. These will be set when Lagoon builds your projects images and are available at runtime.

Docker Compose#

Lagoon doesn't use env vars set using Docker Compose when deploying your projects. You may still choose to set them for local development purposes. Review the Docker Compose env var documentation for more information.

Build Variables#

Use build vars when you want to set an env var that is valid at buildtime, but only for a single deployment. Bulk deployments also support build vars.

Info

Deployments triggered via webhooks won't receive build vars.

Build vars can be set for a deployment using the Lagoon CLI or the Lagoon API.

An example use case would be disabling post rollout tasks, but only for a single deployment:

Lagoon CLILagoon API

lagoon deploy latest --project lagoon-demo --environment main \
--buildvar LAGOON_POSTROLLOUT_DISABLED=true

mutation {
  deployEnvironmentLatest(input: {
    environment: {
      name: "main"
      project: {
        name: "lagoon-demo"
      }
    }
    buildVariables: {
      name: "LAGOON_POSTROLLOUT_DISABLED"
      value: "true"
    }
  })
}

Environment Variable Precedence#

Since env vars may be duplicated in different methods, there's an order in which they're set that determines which value will be used. The order follows, with most specific listed first:

Build vars
Env vars (Lagoon API)
1. Environment specific
2. Project wide
3. Organization wide
Docker env vars
Env files
1. Env vars defined in .lagoon.env.BRANCHNAME
2. Env vars defined in .lagoon.env
3. Env vars defined in .env
4. Env vars defined in .env.defaults

Environment Variables#