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.

After CI asks Lagoon to deploy, Lagoon pulls and builds your code itself. 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 environment when VORTEX_PROVISION_OVERRIDE_DB is 1
  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

Sites that install from a profile skip step 3. Projects with a migration source database also fetch that database before provisioning.

In production, provisioning never sanitizes the database. With the default database provision type, it keeps the existing production database.

Lagoon runs these steps as the post-rollout tasks defined in .lagoon.yml. The same file defines a drush cron job that runs every 15 minutes in the main and develop environments. It also 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 no other code has defined it.

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. That variable lives in .env and is main by default. Otherwise, main, master, release/* and hotfix/* branches count as staging. Every other branch counts as development. The production check comes first, so with the default settings main is production. The production steps in .lagoon.yml check the same 2 things: the environment type and the branch name.

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​

To fetch a database dump from your Lagoon environment for local development or CI builds, run the following command:

ahoy fetch-db

When the database source (VORTEX_FETCH_DB_SOURCE) is lagoon, the command connects over SSH to the VORTEX_FETCH_DB_ENVIRONMENT environment. For Lagoon projects, the installer sets the source to lagoon and the environment to main. Both settings live in .env. The command dumps the database in that environment and downloads the dump. It reuses a dump made earlier the same day, and an existing local dump too. To make a new dump, add --fresh.

Run a custom task​

The custom operation of the vortex-task runner runs a command in a Lagoon environment through the Lagoon CLI. Run it from the project root, on your machine or in a CI job, with an SSH key that your Lagoon user accepts:

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. VORTEX_TASK_CUSTOM_LAGOON_COMMAND holds 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 that reinstalls it when it's 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 confirm that 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 before the 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, here on the main production environment:

  1. Set VORTEX_WEBSERVER_MAINTENANCE_MODE to 1 on the environment:

    lagoon add variable --project your_site --environment main \
      --scope runtime --name VORTEX_WEBSERVER_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_WEBSERVER_MAINTENANCE_MODE

  2. Redeploy the environment:

    lagoon deploy latest --project your_site --environment main

nginx serves the page for every request that reaches it, 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 is public even 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. Requests for other files get the maintenance page too, so keep the page self-contained, with inline styles and images. To preview your changes locally:

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

    VORTEX_WEBSERVER_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