Skip to main content
Version: v2

Variables

Vortex scripts read their settings from environment variables, so you change how a script behaves by setting a variable instead of editing the script.

This page is for developers and DevOps engineers who configure a project's scripts locally, in CI, or on the hosting platform. It explains where a value can come from and which one wins, then documents the project's variables in the variables list.

Variables come in 2 main types:

Project configuration variables are set once during project setup and stay the same for the life of the project. You usually set them in the .env file, or in the environment settings of your CI or hosting provider.

Runtime variables change during the project's life to alter how a script behaves. For example, they change how a deployment runs, or skip deploying a particular branch in CI.

.env and .env.local files​

.env holds the project's shared values and is committed with the code. It lists only the variables a project usually sets. Every other optional variable takes its default from the script that reads it. Add a variable to .env when you need a value other than the default.

.env.local holds your local overrides and secrets, such as passwords and API keys. Create it by copying .env.local.example. Git ignores it, so it stays out of the repository. To apply a change to either file, see Environment > Environment variables.

Override order (bottom values win)​

Each source in the following list overrides the ones before it:

  1. The default value in the script that reads the variable
  2. The default value in the container, taken from the image
  3. The default value in docker-compose.yml
  4. The value in .env, where the last assignment in the file wins
  5. The value in .env.local, where the last assignment in the file wins
  6. The value from the environment

Each script loads .env and then .env.local itself, and skips every variable that's already set in its environment. A value set in your shell, in CI, or on the hosting platform wins over both files.

Naming conventions​

Variables that Vortex scripts own start with the VORTEX_ prefix, which keeps them apart from everything else in the environment. A few go without it, such as WEBROOT and PACKAGE_TOKEN.

Drupal-specific variables start with the DRUPAL_ prefix.

The environment detector reads shared, platform-neutral names that carry neither prefix, such as ENVIRONMENT_TYPE, ENVIRONMENT_PRODUCTION_BRANCH, and LOCALDEV_URL. LOCALDEV_URL, the local development URL, also shares its value with the unprefixed hosting route, LAGOON_ROUTE.

Variables of third-party services, such as NEWRELIC_ENABLED or RENOVATE_TOKEN, keep the names those services use.

Default values​

Every required variable that a Vortex script uses is checked before the script proceeds. An empty or unset one stops the script with an error that names it, such as Missing required value for VORTEX_DEPLOY_WEBHOOK_URL.

Every optional variable has a default value set in the script itself, so the scripts run without extensive configuration. For example, a variable can have a default value in the script and be overridden in the .env file. The CI or hosting provider can override it again for all environments, and then for a specific environment.

A variable with neither a provided value nor a script default is a defect in the template, so report it. Without a default, a condition can take the wrong branch, and the override chain has no base value to fall back to.

An empty value can't override a default. The scripts treat an empty value as unset, so the script default applies instead. The exception is VORTEX_EXPORT_DB_FILE_STRUCTURE_TABLES, where an empty value replaces the cache* default.

Boolean variables​

Boolean variables use 1 for true and 0 for false, so a flag means the same thing in every environment. We don't use true/false, yes/no, or other variations, because some systems interpret true and false differently.

Most scripts compare a flag against 1, so VORTEX_PROVISION_SKIP=true doesn't skip anything. 2 flags, VORTEX_NOTIFY_SKIP and VORTEX_NOTIFY_NEWRELIC_ENABLED, switch on for any value other than an empty one or 0. VORTEX_NOTIFY_NEWRELIC_ENABLED takes true, because it falls back to Lagoon's NEWRELIC_ENABLED. Third-party variables keep their own values, such as RENOVATE_DRY_RUN=true.

Columns of the variables list​

The variables list collects the variables that .env, .env.local.example, docker-compose.yml, the scripts/ directory, CI, and the hosting platforms define or use. A variable that only a Vortex script reads isn't in the list. The script declares it, with a comment and its default, at the top of its file in vendor/drevops/vortex-tooling/src/.

The list has 4 columns:

  • Name: the variable's name.
  • Description: what the variable does, taken from the comment before its definition.
  • Default value: the value the variable gets when you don't set it. UNDEFINED means it has no default.
  • Defined or used in: the files that define or read the variable.

Besides file paths, the Defined or used in column uses these labels:

  • ENVIRONMENT: the variable comes from the environment that runs the scripts, such as your shell or the hosting platform.
  • CI config: the variable comes from the CI configuration or from your CI provider's settings.
  • LAGOON ENVIRONMENT: the variable is set in Lagoon environments.
  • ACQUIA ENVIRONMENT: the variable is set in Acquia environments.

Variables list​

The list below is automatically generated with Shellvar from all Shell scripts.

NameDescriptionDefault valueDefined or used in
AHOY_CONFIRM_RESPONSESet to y to suppress Ahoy prompts.UNDEFINED.env.local.example
AHOY_CONFIRM_WAIT_SKIPWhen Ahoy prompts are suppressed ($AHOY_CONFIRM_RESPONSE is 1), the command will wait for 3 seconds before proceeding. Set this variable to "1" to skip the wait.1.env.local.example
COMPOSE_PROJECT_NAMEDocker Compose project name.

Sets the project name for a Docker Compose project. Influences container and network names.

Defaults to the name of the project directory.
UNDEFINEDENVIRONMENT
DATABASE_CHARSETLocal database charset.

Variable is not used in hosting environment.
utf8mb4docker-compose.yml
DATABASE_COLLATIONLocal database collation.

Variable is not used in hosting environment.
utf8mb4_general_cidocker-compose.yml
DATABASE_DATABASEDatabase name.UNDEFINEDLAGOON ENVIRONMENT
DATABASE_HOSTLocal database host.

Variable is not used in hosting environment.
databasedocker-compose.yml
DATABASE_NAMELocal database name.

Variable is not used in hosting environment.
drupaldocker-compose.yml
DATABASE_PASSWORDLocal database password.

Variable is not used in hosting environment.
drupaldocker-compose.yml
DATABASE_PORTLocal database port.

Variable is not used in hosting environment.
3306docker-compose.yml
DATABASE_USERNAMELocal database user.

Variable is not used in hosting environment.
drupaldocker-compose.yml
DRUPAL_ADMIN_EMAILDrupal admin email. May need to be reset if database was sanitized.UNDEFINED.env
DRUPAL_CLAMAV_ENABLEDEnable ClamAV integration.1.env
DRUPAL_CLAMAV_MODEClamAV mode.

Run ClamAV in either daemon mode by setting it to 0 (or 'daemon') or in executable mode by setting it to 1.
daemon.env
DRUPAL_CONFIG_PATHDrupal configuration directory.

Path from the web root directory to the configuration directory. If not set, the default location is inside a randomly-named directory in the public files path.
../config/default.env
DRUPAL_HASH_SALTDrupal hash salt.

Secures one-time login links, password-reset URLs, and CSRF/form tokens. Set a long, random, unique value for every hosted environment as a platform variable or secret. If not set, a fallback is derived from the database host, which is suitable for local and CI use only.

@see https://www.vortextemplate.com/docs/development/settings
<generated from database host>ENVIRONMENT
DRUPAL_MAINTENANCE_THEMEDrupal maintenance theme name.your_site_theme.env
DRUPAL_PRIVATE_FILESPath to private files.${DRUPAL_PUBLIC_FILES}/privatedocker-compose.yml
DRUPAL_PROFILEDrupal profile name.standard.env
DRUPAL_PUBLIC_FILESPath to public files../${WEBROOT}/sites/default/filesdocker-compose.yml
DRUPAL_REDIS_ENABLEDEnable Redis integration. See settings.redis.php for details.1.env
DRUPAL_SEARCH_INDEX_SKIPSkip search indexing.UNDEFINED.env
DRUPAL_SHIELD_PRINTShield message.Restricted access..env
DRUPAL_SITE_EMAILDrupal site email. Used only when installing from profile.webmaster@your-site-domain.example.env
DRUPAL_SITE_NAMEDrupal site name. Used only when installing from profile.${VORTEX_PROJECT}.env
DRUPAL_STAGE_FILE_PROXY_ORIGINStage file proxy origin.

If using Shield, the HTTP authentication credentials will be automatically added to the origin URL.
https://www.your-site-domain.example.env
DRUPAL_STORYBOOK_SKIPSkip building the Storybook component library during provisioning.UNDEFINED.env
DRUPAL_TEMPORARY_FILESPath to temporary files.${DRUPAL_PRIVATE_FILES}/tmpdocker-compose.yml
DRUPAL_THEMEDrupal theme name.your_site_theme.env
DRUPAL_TRUSTED_HOSTSTrusted host patterns.

Comma-separated list of domains for trusted host patterns. These domains will be added to the trusted host patterns alongside any other routes defined by the hosting provider.
your-site-domain.example,www.your-site-domain.example.env
ENVIRONMENT_PRODUCTION_BRANCHDedicated branch to identify the production environment.main.env
ENVIRONMENT_TYPEOverride the detected environment type.

Set before detection to force a specific environment type. Read by the environment detector.
UNDEFINEDENVIRONMENT
LAGOON_PROJECTLagoon project name. May be different from $VORTEX_PROJECT.

Update drush/sites/lagoon.site.yml if you update this value.
your_site.env
LOCALDEV_URLLocal development URL.

Based on the $COMPOSE_PROJECT_NAME environment variable, which is set by Docker Compose to the name of the project directory.

Override only if you need to use a different URL than the default.
example-site.docker.amazee.io.env.local.example
NEWRELIC_ENABLEDEnable New Relic in Lagoon environment.

Set as project-wide variable.
UNDEFINEDLAGOON ENVIRONMENT
NEWRELIC_LICENSENew Relic license.

Set as project-wide variable.
UNDEFINEDLAGOON ENVIRONMENT
PACKAGE_TOKENGitHub token used to overcome API rate limits or access private repositories. @see https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-tokenUNDEFINED.env.local.example, scripts/vortex-tooling.sh
RENOVATE_DEPENDENCY_DASHBOARDWhether to enable self-hosted Renovate bot dashboard.falseCI config
RENOVATE_DRY_RUNWhether to allow self-hosted Renovate bot make changes to the repository.falseCI config
RENOVATE_GIT_AUTHORCommit author for self-hosted Renovate bot.'Renovate Self Hosted <renovatebot@your-site-domain.example>'CI config
RENOVATE_REPOSITORIESRenovate repositories to manage. Set as "organization/repository".UNDEFINEDCI config
RENOVATE_TOKENSelf-hosted Renovate bot token. Create a GitHub token with a permission to write to a repository.UNDEFINEDCI config
TZThe timezone used within the containers.UTC.env
VORTEX_ACQUIA_APP_NAMEAcquia application name.UNDEFINED.env
VORTEX_ACQUIA_KEYAcquia Cloud API key.UNDEFINED.env.local.example
VORTEX_ACQUIA_SECRETAcquia Cloud API secret.UNDEFINED.env.local.example
VORTEX_CI_ARTIFACTSDirectory to store test artifacts in CI./tmp/artifactsCI config
VORTEX_CI_BEHAT_IGNORE_FAILUREIgnore Behat test failures.UNDEFINEDCI config
VORTEX_CI_BEHAT_PROFILETest Behat profile to use in CI. If not set, the default profile will be used.UNDEFINEDCI config
VORTEX_CI_CODE_COVERAGE_PR_COMMENT_SKIPSkip posting code coverage report as a PR comment.UNDEFINEDCI config
VORTEX_CI_CODE_COVERAGE_THRESHOLDCode coverage threshold percentage. Build fails if coverage is below this value.90CI config
VORTEX_CI_COMPOSER_AUDIT_IGNORE_FAILUREIgnore composer audit failures.UNDEFINEDCI config
VORTEX_CI_COMPOSER_NORMALIZE_IGNORE_FAILUREIgnore composer normalize failures.UNDEFINEDCI config
VORTEX_CI_COMPOSER_VALIDATE_IGNORE_FAILUREIgnore composer validate failures.UNDEFINEDCI config
VORTEX_CI_DCLINT_IGNORE_FAILUREIgnore DCLint failures.UNDEFINEDCI config
VORTEX_CI_FREE_DISK_SPACESet to 1 to remove preinstalled toolchains from the GitHub Actions runner and free disk space.UNDEFINEDCI config
VORTEX_CI_GHERKIN_LINT_IGNORE_FAILUREIgnore Gherkin Lint failures.UNDEFINEDCI config
VORTEX_CI_HADOLINT_IGNORE_FAILUREIgnore Hadolint failures.UNDEFINEDCI config
VORTEX_CI_JEST_IGNORE_FAILUREIgnore Jest test failures.UNDEFINEDCI config
VORTEX_CI_NODEJS_LINT_IGNORE_FAILUREIgnore NodeJS linters failures.UNDEFINEDCI config
VORTEX_CI_NPM_AUDIT_IGNORE_FAILUREIgnore npm audit failures.UNDEFINEDCI config
VORTEX_CI_PHPCS_IGNORE_FAILUREIgnore PHPCS failures.UNDEFINEDCI config
VORTEX_CI_PHPSTAN_IGNORE_FAILUREIgnore PHPStan failures.UNDEFINEDCI config
VORTEX_CI_PHPUNIT_IGNORE_FAILUREIgnore PHPUnit test failures.UNDEFINEDCI config
VORTEX_CI_RECTOR_IGNORE_FAILUREIgnore Rector failures.UNDEFINEDCI config
VORTEX_CI_TEST_RESULTSDirectory to store test results in CI./tmp/testsCI config
VORTEX_CI_TWIG_CS_FIXER_IGNORE_FAILUREIgnore Twig CS Fixer failures.UNDEFINEDCI config
VORTEX_CI_WORKTREE_CHANGES_IGNORE_FAILUREIgnore working tree check failures.UNDEFINEDCI config
VORTEX_CONTAINER_REGISTRYContainer registry name.

Provide port, if required as <server_name>:<port>.
docker.io.env
VORTEX_CONTAINER_REGISTRY_PASSThe password (token) to log into the container registry.UNDEFINED.env.local.example
VORTEX_CONTAINER_REGISTRY_USERThe username to log into the container registry.UNDEFINED.env.local.example
VORTEX_DB_DIRDatabase dump directory.

The directory is used to store the database dump files for import and export.
./.data.env
VORTEX_DB_FILEDatabase dump file name.

The file is used to import the database into an empty database container.
db.sql.env
VORTEX_DB_IMAGEName of the database container image to use.

See https://github.com/drevops/mariadb-drupal-data to seed your DB image.
UNDEFINED.env
VORTEX_DB_IMAGE_BASEName of the database fall-back container image to use.

If the image specified in $VORTEX_DB_IMAGE does not exist and base image was provided - it will be used as a "clean slate" for the database.
UNDEFINED.env
VORTEX_DEBUGSet to 1 to print debug information in Vortex scripts.UNDEFINED.env.local.example
VORTEX_DEPLOY_ALLOW_LABELLabel that authorizes a pull request deployment. When set, a PR is deployed only if it carries this label.UNDEFINEDCI config
VORTEX_DEPLOY_ALLOW_SKIPFlag to allow skipping of a deployment using additional flags.UNDEFINEDCI config
VORTEX_DEPLOY_SKIPSkip all deployments.UNDEFINEDCI config
VORTEX_DEPLOY_SKIP_BRANCHESBranch names to skip deployment for (single value or comma-separated list).UNDEFINEDCI config
VORTEX_DEPLOY_SKIP_PRSPull request numbers to skip deployment for (single value or comma-separated list).UNDEFINEDCI config
VORTEX_DEPLOY_TYPESDeployment occurs when tests pass in the CI environment. @see https://www.vortextemplate.com/docs/deploymentartifact.env
VORTEX_EXPORT_DB_CONTAINER_REGISTRY_PUSH_PROCEEDProceed with container image push after it was exported.UNDEFINEDCI config
VORTEX_FETCH_DB2_ACQUIA_DB_NAMEAcquia database name to fetch the second database from.your_site.env
VORTEX_FETCH_DB2_ENVIRONMENTEnvironment to fetch the second database from.

Applies to hosting environments.
prod.env
VORTEX_FETCH_DB2_FILESecond database dump file name.db2.sql.env
VORTEX_FETCH_DB2_FTP_FILESecond database dump FTP file name.db2.sql.env
VORTEX_FETCH_DB2_FTP_HOSTSecond database dump FTP host.UNDEFINED.env
VORTEX_FETCH_DB2_FTP_PORTSecond database dump FTP port.21.env
VORTEX_FETCH_DB2_S3_BUCKETAWS S3 bucket name for second database fetch.UNDEFINED.env
VORTEX_FETCH_DB2_S3_REGIONAWS S3 region.ap-southeast-2.env
VORTEX_FETCH_DB2_SOURCESecond database fetch source.url.env
VORTEX_FETCH_DB2_URLSecond database dump file sourced from a URL.

HTTP Basic Authentication credentials should be embedded into the value.
UNDEFINED.env
VORTEX_FETCH_DB_ACQUIA_DB_NAMEAcquia database name to fetch the database from.your_site.env
VORTEX_FETCH_DB_ENVIRONMENTEnvironment to fetch the database from.

Applies to hosting environments. Note that depending on the hosting provider, this variable may represent a branch name or an environment name.
prod.env
VORTEX_FETCH_DB_FORCEAlways override existing fetched DB dump.1.env.local.example
VORTEX_FETCH_DB_FTP_FILEDatabase dump FTP file name.db.sql.env
VORTEX_FETCH_DB_FTP_HOSTDatabase dump FTP host.UNDEFINED.env
VORTEX_FETCH_DB_FTP_PASSDatabase dump FTP password.UNDEFINED.env.local.example
VORTEX_FETCH_DB_FTP_PORTDatabase dump FTP port.21.env
VORTEX_FETCH_DB_FTP_USERDatabase dump FTP user.UNDEFINED.env.local.example
VORTEX_FETCH_DB_S3_ACCESS_KEYAWS access key for S3 database fetch.UNDEFINED.env.local.example
VORTEX_FETCH_DB_S3_BUCKETAWS S3 bucket name for database fetch.UNDEFINED.env
VORTEX_FETCH_DB_S3_REGIONAWS S3 region.ap-southeast-2.env
VORTEX_FETCH_DB_S3_SECRET_KEYAWS secret key for S3 database fetch.UNDEFINED.env.local.example
VORTEX_FETCH_DB_SOURCEDatabase fetch source.url.env
VORTEX_FETCH_DB_URLDatabase dump file sourced from a URL.

HTTP Basic Authentication credentials should be embedded into the value.
UNDEFINED.env
VORTEX_FRONTEND_BUILD_SKIPSkip building of the front-end assets inside the container image.

Set to 1 to build theme assets on the host or as part of deployment instead of during the container image build.
UNDEFINED.env
VORTEX_NOTIFY_ACQUIA_SKIPSkip sending of deployment notifications in Acquia environment.UNDEFINEDACQUIA ENVIRONMENT
VORTEX_NOTIFY_CHANNELSThe channels of the notifications.

A combination of comma-separated values: email,slack,newrelic,github,jira,webhook,diffy
email.env
VORTEX_NOTIFY_EMAIL_FROMAn email address to send notifications from.

Applies to email notifications.
webmaster@your-site-domain.example.env
VORTEX_NOTIFY_EMAIL_RECIPIENTSEmail address(es) to send notifications to.

Applies to email notifications.

Multiple names can be specified as a comma-separated list of email addresses with optional names in the format "email
name". Example: "to1@example.comJane Doe, to2@example.com
VORTEX_NOTIFY_GITHUB_TOKENGitHub token.

@see https://www.vortextemplate.com/docs/deployment/notifications/github
UNDEFINEDACQUIA ENVIRONMENT, LAGOON ENVIRONMENT
VORTEX_NOTIFY_JIRA_TOKENJIRA API token.

@see https://www.vortextemplate.com/docs/deployment/notifications/jira
UNDEFINEDACQUIA ENVIRONMENT, LAGOON ENVIRONMENT
VORTEX_NOTIFY_JIRA_USER_EMAILJIRA user email address.user@example.com.env
VORTEX_NOTIFY_NEWRELIC_APIKEYNewRelic API key, usually of type 'USER'.

@see https://www.vortextemplate.com/docs/deployment/notifications/newrelic
UNDEFINEDACQUIA ENVIRONMENT, LAGOON ENVIRONMENT
VORTEX_NOTIFY_SLACK_WEBHOOKSlack webhook URL. The incoming Webhook URL from your Slack app configuration. @see https://www.vortextemplate.com/docs/deployment/notifications/slackUNDEFINEDACQUIA ENVIRONMENT, LAGOON ENVIRONMENT
VORTEX_NOTIFY_WEBHOOK_URLWebhook URL to send notifications to.UNDEFINED.env, ACQUIA ENVIRONMENT, LAGOON ENVIRONMENT
VORTEX_PROJECTProject name.

Drives internal naming within the codebase. Does not affect the names of containers and development URL - those depend on the project directory and can be overridden with $COMPOSE_PROJECT_NAME.
your_site.env
VORTEX_PROVISION_ACQUIA_SKIPSkip Drupal site provisioning in Acquia environment.UNDEFINEDACQUIA ENVIRONMENT
VORTEX_PROVISION_FALLBACK_TO_PROFILEFallback to profile installation if the database dump is not available.

When enabled and the provision type is set to "database", the site will be installed from the profile if the database dump file or container image is not available.
UNDEFINED.env
VORTEX_PROVISION_OVERRIDE_DBOverwrite a database if it exists.

Usually set to 0 in deployed environments and can be temporary set to 1 for a specific deployment. Set this to 1 in .env.local to override when developing locally.
UNDEFINED.env, .env.local.example
VORTEX_PROVISION_SANITIZE_DB_EMAILSanitization email pattern.

Applied if database sanitization is enabled. @see https://www.vortextemplate.com/docs/development/provision#database-sanitization
user_%uid@your-site-domain.example.env
VORTEX_PROVISION_SANITIZE_DB_PASSWORDPassword replacement used for sanitized database.<RANDOM STRING>.env
VORTEX_PROVISION_SANITIZE_DB_REPLACE_USERNAME_WITH_EMAILReplace username with email after database sanitization. Useful when email is used as username.UNDEFINED.env
VORTEX_PROVISION_SANITIZE_DB_SKIPSkip database sanitization.

Database sanitization is enabled by default in all non-production environments and is always skipped in the production environment. @see https://www.vortextemplate.com/docs/development/provision#database-sanitization
UNDEFINED.env
VORTEX_PROVISION_TYPESet to 'profile' to install a site from profile instead of the database dump.database.env
VORTEX_PROVISION_USE_MAINTENANCE_MODEPut the site into a maintenance mode during site provisioning.1.env
VORTEX_PROVISION_VERIFY_CONFIG_UNCHANGED_AFTER_PROVISIONVerify that configuration was not changed by post-provision operations. If enabled and config files are present, the provision will fail if any active configuration item differs from the exported configuration once configuration imports, deployment hooks and deploy steps have run.UNDEFINED.env
VORTEX_PROVISION_VERIFY_CONFIG_UNCHANGED_AFTER_UPDATEVerify that configuration was not changed by database updates. If enabled and config files are present, the provision will fail if database update hooks modify active configuration, preventing drush config:import from silently overwriting those changes.UNDEFINED.env
VORTEX_PURGE_CACHE_ACQUIA_SKIPSkip purging of edge cache in Acquia environment.UNDEFINEDACQUIA ENVIRONMENT
VORTEX_RELEASE_VERSION_SCHEMEVersioning scheme used for releases.

Can be one of: calver, semver, other @see https://www.vortextemplate.com/docs/releasing
calver.env
VORTEX_TASK_COPY_DB_ACQUIA_SKIPSkip copying of database between Acquia environment.UNDEFINEDACQUIA ENVIRONMENT
VORTEX_TASK_COPY_FILES_ACQUIA_SKIPSkip copying of files between Acquia environment.UNDEFINEDACQUIA ENVIRONMENT
VORTEX_UNBLOCK_ADMINUnblock admin account when logging in.1.env
VORTEX_WEBSERVER_MAINTENANCE_MODEServe the static maintenance page from the webserver container.

Set to 1 on a single environment, then redeploy it. Every request is then answered with HTTP status 503 and the maintenance page, and none reaches PHP. @see https://www.vortextemplate.com/docs/hosting/lagoon#serve-a-maintenance-page
UNDEFINEDLAGOON ENVIRONMENT
WEBROOTName of the web root directory containing a Drupal codebase.web.env