Skip to main content
Version: v2

Lagoon

Lagoon is an open-source container-based hosting platform that provides automated deployments for Drupal applications using Docker and Kubernetes.

For general Lagoon documentation, refer to the Lagoon Documentation.

This page covers how the site behaves once it runs on Lagoon. For how code gets there from CI, see Lagoon deployment.

Integration​

Vortex provides the following integration with Lagoon:

Tasks​

With Vortex, you can:

  • Fetch a database from a Lagoon environment for local development or CI
  • Trigger deployments to Lagoon environments - see Lagoon deployment
  • Run custom commands on Lagoon environments

When running these tasks, your .env and .env.local files are used as the source for the project name and SSH configuration.

Deployment automation​

When code is deployed, Vortex automatically:

  1. Provisions the site - Runs database updates, imports configuration, clears caches
  2. Sends notifications - Notifies configured channels about the deployment

This is implemented using post-rollout tasks defined in the .lagoon.yml configuration file, which also defines per-environment cron jobs and routes.

Environment detection​

Vortex automatically detects when running on Lagoon and applies the Lagoon-specific Drupal settings through the drevops/environment-detector package. This includes Lagoon-specific configurations for caching, file paths, and environment variables provided by the platform.

Onboarding​

Lagoon onboarding is part of the project setup flow. See Set up hosting in the Installation guide and select Lagoon.

Routine operations​

Fetch database​

Download a current database dump from your Lagoon environment for local development or CI builds:

ahoy fetch-db

This wraps the provider-native Lagoon CLI. If a lagoon binary is already on your PATH, Vortex uses it as-is. Otherwise it downloads a pinned release into a cache directory (.artifacts/tmp by default, overridable with VORTEX_LAGOONCLI_PATH) and reuses that copy on later runs, so nothing needs to be pre-installed. This works the same on a developer host and inside the Lagoon environment, letting the same command pull the production database into a non-production environment without a round-trip through a developer machine.

When running inside the Lagoon environment, set VORTEX_FETCH_DB_SSH_FILE=false to skip SSH key setup and use the ambient Lagoon identity instead of a developer SSH key.

The instance is registered in an isolated, per-run config file rather than your default ~/.lagoon.yml, so any Lagoon configuration you already have locally is left untouched.

The dump is created on demand with Lagoon's built-in drush-sqldump task, so it reflects the current state of the source database. To avoid re-dumping on every run, a recent completed dump is reused when its artifact can still be downloaded, within 24 hours by default (overridable with VORTEX_FETCH_DB_LAGOON_REUSE_MAX_AGE, in seconds). Creating a fresh dump is always the fallback when no reusable dump is available. Force a new dump with:

ahoy fetch-db --fresh

Run a custom task​

Run an arbitrary command in a Lagoon environment through the platform-agnostic task runner, which drives the Lagoon CLI:

VORTEX_PLATFORM=lagoon \
VORTEX_TASK_CUSTOM_LAGOON_BRANCH=develop \
VORTEX_TASK_CUSTOM_LAGOON_COMMAND="drush cron" \
./vendor/bin/vortex-task custom

The task reads the project name and SSH configuration from your .env and .env.local files; VORTEX_TASK_CUSTOM_LAGOON_BRANCH selects the environment and VORTEX_TASK_CUSTOM_LAGOON_COMMAND is the command to run there.