Skip to main content
Version: v1

Lagoon

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

This page is for the lead or DevOps engineer who runs a project built from Vortex on Lagoon. It explains what happens on Lagoon during a deployment, how the site detects its environment, and how to run the routine operations. For general Lagoon documentation, see the Lagoon documentation.

Lagoon pulls and builds your code itself after CI asks it to deploy; Lagoon deployment covers that part.

Integration​

The following sections describe what the integration does on Lagoon.

Tasks​

Vortex gives you the following tasks on Lagoon:

  • 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

These tasks read the project name (LAGOON_PROJECT) from your .env file and the SSH key settings, such as VORTEX_FETCH_DB_SSH_FILE, from .env.local.

Deployment automation​

On each deployment, Vortex runs these steps on Lagoon:

  1. Notifies configured channels that the deployment is starting
  2. In production, backs up the database to web/sites/default/files/private/pre_deployment_backups
  3. In every other environment, fetches the database dump that provisioning imports into a new environment, or into an existing one when the database override is on
  4. Provisions the site: runs database updates, imports configuration, rebuilds caches, and runs Drupal's deploy hooks (drush deploy:hook)
  5. Notifies configured channels about the finished deployment

In production, provisioning never sanitizes the database. With the default database provision type, it also never overwrites the existing production database. Step 3 isn't there when the site installs from a profile, and projects with a migration source database fetch that database too, before provisioning.

The post-rollout tasks in the .lagoon.yml configuration file run these steps. The same file runs a drush cron job every 15 minutes in both the main and the develop environments, and defines monitoring URLs for both. Other environments get no cron job.

Environment detection​

Vortex detects Lagoon by its LAGOON_KUBERNETES variable and then applies the settings in web/sites/default/includes/providers/settings.lagoon.php. That file applies the following settings:

  • It maps the environment to an environment type.
  • It sets reverse_proxy to TRUE and reverse_proxy_header to HTTP_TRUE_CLIENT_IP.
  • It gives each branch its own cache prefix, made of the project name and the branch.
  • It trusts the hostnames of the environment's Lagoon routes, the internal nginx-php hostname, and any amazee.io subdomain.
  • It defines the LAGOON_VERSION constant as 1 when nothing else has.

An environment is production when Lagoon sets its LAGOON_ENVIRONMENT_TYPE variable to production, or when its branch name equals VORTEX_LAGOON_PRODUCTION_BRANCH exactly. VORTEX_LAGOON_PRODUCTION_BRANCH lives in .env and is main by default. Otherwise, main, master, release/*, and hotfix/* branches count as staging, and every other branch as development. The production check comes first, so main counts as staging only when it isn't the production branch. The production steps in .lagoon.yml use the same 2 checks.

Onboarding​

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

Routine operations​

The following sections cover the operations you run against Lagoon environments.

Fetch database​

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

ahoy fetch-db

When the database source (VORTEX_FETCH_DB_SOURCE) is lagoon, the installer's default for Lagoon projects, the command connects over SSH to the VORTEX_FETCH_DB_ENVIRONMENT environment, which the installer sets to main. Both settings live in .env. The command dumps the database there and downloads the dump. A dump made earlier the same day is reused, and so is an existing local dump; add --fresh to make a new one.

Run a custom task​

Run an arbitrary command in a Lagoon environment through the platform-agnostic task runner, which drives the Lagoon CLI. Run it from the project root on your machine or in a CI job, wherever an SSH key that your Lagoon user accepts is available:

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

VORTEX_TASK_CUSTOM_LAGOON_BRANCH selects the environment and VORTEX_TASK_CUSTOM_LAGOON_COMMAND is the command to run there. The task reads the project name and SSH configuration from your .env and .env.local files. Its other settings have defaults:

  • VORTEX_TASK_CUSTOM_LAGOON_NAME - the task name shown in Lagoon (default: Automation task)
  • VORTEX_TASK_CUSTOM_LAGOON_PROJECT - the Lagoon project (default: the value of LAGOON_PROJECT)
  • VORTEX_TASK_CUSTOM_LAGOON_INSTANCE, VORTEX_TASK_CUSTOM_LAGOON_INSTANCE_GRAPHQL, VORTEX_TASK_CUSTOM_LAGOON_INSTANCE_HOSTNAME, and VORTEX_TASK_CUSTOM_LAGOON_INSTANCE_PORT - the Lagoon instance, with the same defaults as the Lagoon deployment
  • VORTEX_TASK_CUSTOM_LAGOON_SSH_FINGERPRINT and VORTEX_TASK_CUSTOM_LAGOON_SSH_FILE - the SSH key (default file: ~/.ssh/id_rsa)
  • VORTEX_TASK_CUSTOM_LAGOON_CLI_PATH, VORTEX_TASK_CUSTOM_LAGOON_CLI_VERSION, and VORTEX_TASK_CUSTOM_LAGOON_CLI_FORCE_INSTALL - the Lagoon CLI's install directory (default: /tmp), its version (default: v0.32.0), and a flag to reinstall it when one is already on the path

Confirm that Lagoon accepted the task. With the default name, the output shows a Created line for the task, then ends with the finish line:

[ OK ] Created Automation task: project: your_site, branch: develop.
[ OK ] Finished Lagoon task Automation task.

These lines mean Lagoon queued the task, not that the command succeeded, because the Lagoon CLI returns as soon as the task exists. Follow the task and its output in the environment's tasks in the Lagoon UI. When Lagoon rejects the request, the script stops with the Lagoon CLI's error and prints no Created line.

The runner's other operations, copy-db, copy-files, and purge-cache, exist only for Acquia. On Lagoon, they stop with an error that says the operation is not supported on the "lagoon" platform.

Run Drush against remote environments​

The shipped drush/sites/lagoon.site.yml file defines an alias for every environment of the project, such as @lagoon.develop or @lagoon.pr-123. Drush aliases shows how to load your SSH key and run commands with them.

Serve a maintenance page​

A static maintenance page takes an environment offline when Drupal must stay down, for example during a database migration or an incident. The nginx container answers every request with HTTP status 503 and the page, so no request reaches PHP. Drupal's own maintenance mode runs in PHP and needs a working database.

Lagoon applies a changed variable on the next deployment, so each switch is a variable change followed by a redeployment. To turn the page on:

  1. Set VORTEX_NGINX_MAINTENANCE_MODE to 1 on the environment:

    lagoon add variable --project your_site --environment main \
      --scope runtime --name VORTEX_NGINX_MAINTENANCE_MODE --value 1

    Only the value 1 turns the page on.

  2. Redeploy the environment:

    lagoon deploy latest --project your_site --environment main

  3. Confirm that the environment answers with 503:

    curl -s -o /dev/null -w "%{http_code}\n" https://www.your-site-domain.example

To bring the site back:

  1. Delete the variable:

    lagoon delete variable --project your_site --environment main \
      --name VORTEX_NGINX_MAINTENANCE_MODE

  2. Redeploy the environment:

    lagoon deploy latest --project your_site --environment main

The page covers every request that reaches the site's web server, including static files, robots.txt, and Lagoon's /.lagoonhealthz check. Lagoon checks the container's health on a separate status port, so the environment stays healthy. Shield runs in Drupal, so the page stays public on environments that Shield protects.

The page is .docker/config/nginx/maintenance.html. The maintenance.conf file in the same directory holds the rules that serve it. Keep the page self-contained, with inline styles and images, because requests for other files get the maintenance page too. To preview your changes locally:

  1. Rebuild and recreate the nginx container with the variable set:

    VORTEX_NGINX_MAINTENANCE_MODE=1 ahoy up --build nginx

    The local site shows the maintenance page.

  2. Recreate the container without the variable to bring the site back:

    ahoy up nginx