Version: v1

Lagoon deployment

In a Lagoon deployment, the deployment script uses the Lagoon CLI to ask the Lagoon hosting platform to deploy your branch or pull request. Lagoon pulls the code from your repository and builds it itself, so CI packages nothing.

This page is for the lead or DevOps engineer who connects a project's CI to Lagoon. It covers what the deployment script asks Lagoon to do, the variables that configure it and the setup steps. For how the site runs on Lagoon after a deployment, see Lagoon hosting.

How it works

When $VORTEX_DEPLOY_TYPES includes lagoon, the deployment script installs the Lagoon CLI if it isn't on the path yet. The script points the CLI at the configured Lagoon instance and requests a deployment over SSH. Lagoon then runs these steps:

Pulls the latest code from your repository
Builds container images using your docker-compose.yml
Deploys containers to Kubernetes
Runs post-rollout tasks defined in .lagoon.yml

The script finishes after Lagoon accepts the request, without waiting for the build. Watch the build in the environment's deployments in the Lagoon UI.

Before it deploys, the script checks whether Lagoon already has an environment for the branch or pull request. A new branch or pull request gets a fresh deployment, and an existing environment gets a redeployment.

For a redeployment, the script sets VORTEX_PROVISION_OVERRIDE_DB on the environment while Lagoon queues the build: 1 when the deployment action is deploy_override_db, and 0 for any other action. After Lagoon queues the build, the script restores VORTEX_PROVISION_OVERRIDE_DB to its earlier value, or removes it if the environment had none. When the script can't read the environment's variables, it leaves VORTEX_PROVISION_OVERRIDE_DB unchanged and prints a warning.

These rules decide what happens to a branch's environment:

Lagoon skips a new branch that doesn't match the branch pattern set on the Lagoon project.
Lagoon skips a pull request when the Lagoon project doesn't deploy pull requests.
The destroy deployment action deletes the branch's environment.

When Lagoon refuses a deployment because the project has reached its environment limit, the script reports it. The build still passes unless you set VORTEX_DEPLOY_LAGOON_FAIL_ENV_LIMIT_EXCEEDED to 1 to fail it.

Lagoon doesn't support tag deployments, so for a tag the script reports this, skips the deployment and passes.

Configuration

Configure the deployment with the variables in the following table, then follow the setup steps.

Environment variables

The Deployment overview explains the Location values and how the script loads .env. The following table lists the variables that the Lagoon deployment script reads:

Variable	Required	Default	Location	Description
`VORTEX_DEPLOY_LAGOON_PROJECT`	Yes, unless `LAGOON_PROJECT` is set	Value of `LAGOON_PROJECT`	`.env`	Your Lagoon project name
`VORTEX_DEPLOY_LAGOON_INSTANCE`	No	`amazeeio`	`.env`	Lagoon instance name
`VORTEX_DEPLOY_LAGOON_INSTANCE_GRAPHQL`	No	`https://api.lagoon.amazeeio.cloud/graphql`	`.env`	Lagoon GraphQL endpoint
`VORTEX_DEPLOY_LAGOON_INSTANCE_HOSTNAME`	No	`ssh.lagoon.amazeeio.cloud`	`.env`	Lagoon SSH hostname
`VORTEX_DEPLOY_LAGOON_INSTANCE_PORT`	No	`32222`	`.env`	Lagoon SSH port
`VORTEX_DEPLOY_LAGOON_BRANCH`	No	Value of `VORTEX_DEPLOY_BRANCH`	CI	Branch to deploy
`VORTEX_DEPLOY_LAGOON_PR`	No	Value of `VORTEX_DEPLOY_PR`	CI	Pull request number to deploy
`VORTEX_DEPLOY_LAGOON_PR_HEAD`	No	Value of `VORTEX_DEPLOY_PR_HEAD`	CI	Head commit of the pull request
`VORTEX_DEPLOY_LAGOON_PR_BASE_BRANCH`	No	Value of `VORTEX_DEPLOY_PR_BASE_BRANCH`, then `develop`	CI	Branch the pull request targets; the shipped CI configs don't set it
`VORTEX_DEPLOY_LAGOON_ACTION`	No	Value of `VORTEX_DEPLOY_ACTION`, then `create`	CI	Deployment action: `destroy` deletes the environment, `deploy_override_db` overwrites the database on a redeployment and any other value deploys
`VORTEX_DEPLOY_LAGOON_SSH_FINGERPRINT`	No	Value of `VORTEX_DEPLOY_SSH_FINGERPRINT`	CI	Fingerprint of the SSH key used to authenticate
`VORTEX_DEPLOY_LAGOON_SSH_FILE`	No	Value of `VORTEX_DEPLOY_SSH_FILE`, then `~/.ssh/id_rsa`	CI	SSH key file used when no fingerprint is set
`VORTEX_DEPLOY_LAGOON_LAGOONCLI_VERSION`	No	Value of `VORTEX_LAGOONCLI_VERSION`, then `v0.32.0`	CI	Lagoon CLI version to install
`VORTEX_DEPLOY_LAGOON_LAGOONCLI_PATH`	No	Value of `VORTEX_LAGOONCLI_PATH`, then `/tmp`	CI	Directory the Lagoon CLI is installed into
`VORTEX_DEPLOY_LAGOON_LAGOONCLI_FORCE_INSTALL`	No	Value of `VORTEX_LAGOONCLI_FORCE_INSTALL`	CI	Any value installs the Lagoon CLI even when it's already on the path
`VORTEX_DEPLOY_LAGOON_FAIL_ENV_LIMIT_EXCEEDED`	No	`0`	CI	Fail the build when the Lagoon environment limit is exceeded (`1`) or pass it (`0`)

CI sets the branch, pull request and head commit variables for you. The Variables reference lists the same variables with the script that reads each variable.

Setup

To set up Lagoon deployment:

Add lagoon to the comma-separated VORTEX_DEPLOY_TYPES list in your .env file. With lagoon as the only type, the line reads:
.env
```
VORTEX_DEPLOY_TYPES=lagoon
```
Set your Lagoon project name in your .env file:
.env
```
LAGOON_PROJECT=your-project-name
```
Give CI an SSH key that your Lagoon user accepts:
- On GitHub Actions, add the private key as the VORTEX_DEPLOY_SSH_PRIVATE_KEY repository secret.
- On CircleCI, add the private key under Project Settings > SSH Keys and set its fingerprint as deploy_ssh_fingerprint in .circleci/config.yml.
The CLI connects over SSH, so a missing key fails the deployment.

Confirm that the next deployment reached Lagoon. The deploy job log shows Requested deployment of environment or Requested redeployment of environment with your project and branch, followed by [ OK ] Finished Lagoon deployment. Without a Lagoon environment limit exceeded. line, that means Lagoon accepted the request. The build's own result shows in the Lagoon UI.

Post-deployment automation

After Lagoon rolls out the new containers, the post-rollout tasks in .lagoon.yml run these steps:

Back up or fetch the database
Provision the site
Send notifications

See Lagoon hosting for every step.

Environments

The shipped .lagoon.yml sets up the environments with the following settings:

A drush cron job every 15 minutes and monitoring URLs for the main and develop branches.
A redirect from HTTP to HTTPS on every route (the routes key sets insecure to Redirect).
The deployed Git SHA as an environment variable (git_sha: 'true'), which the notifications use.
Commented-out blocks for a custom SSL certificate and for private container registries.

The post-rollout tasks in .lagoon.yml treat an environment as production in 2 cases: Lagoon marks it as production, or its branch matches VORTEX_LAGOON_PRODUCTION_BRANCH (default: main).

Configure the rest per project in Lagoon itself: which branches get an environment, their types and the pull request (ephemeral) environments. See Lagoon environment types.

On GitHub, the shipped .github/workflows/close-pull-request.yml workflow runs when a pull request closes. The workflow forwards the event to the Lagoon webhook endpoint, so Lagoon removes the pull request's environment. The endpoint defaults to https://hooks.lagoon.amazeeio.cloud/. To use another Lagoon instance, set the LAGOON_WEBHOOK_ENDPOINT repository variable.

The installer keeps this workflow for CircleCI projects too, so the workflow still runs if GitHub Actions is enabled for the repository. The CircleCI config has no step that removes pull request environments.

How it works​

Configuration​

Environment variables​

Setup​

Post-deployment automation​

Environments​

See also​