Skip to content


The Lagoon logo is a blue hexagon split in two pieces with an L-shaped cut

Lagoon - the developer-focused application delivery platform for Kubernetes

Table of Contents

  1. Project Description
  2. Usage
  3. Architecture
  4. Testing
  5. Other Lagoon Components
  6. Contribution
  7. History
  8. Connect

Project Description

Lagoon solves what developers are dreaming about: A system that allows developers to locally develop their code and their services with Docker and run the exact same system in production. The same container images, the same service configurations and the same code.

Lagoon is an application delivery platform. Its primary focus is as a cloud-native tool for the deployment, management, security and operation of many applications. Lagoon greatly reduces the requirement on developers of those applications to have cloud-native experience or knowledge.

Lagoon has been designed to handle workloads that have been traditionally more complex to make cloud-native (such as CMS, LMS, and other multi-container applications), and to do so with minimal retraining or reworking needed for the developers of those applications.

Lagoon is fully open-source, built on open-source tools, built collaboratively with our users.



Note that is not necessary to install Lagoon on to your local machine if you are looking to maintain websites hosted on Lagoon.

Lagoon can be installed:

For more information on developing or contributing to Lagoon, head to

For more information on installing and administering Lagoon, head to


Lagoon comprises two main components: Lagoon Core and Lagoon Remote. It's also built on several other third-party services, Operators and Controllers. In a full production setting, we recommend installing Lagoon Core and Remote into different Kubernetes Clusters. A single Lagoon Core installation is capable of serving multiple Remotes, but they can also be installed into the same cluster if preferred.

To enhance security, Lagoon Core does not need administrator-level access to the Kubernetes clusters that are running Lagoon Remote. All inter-cluster communication happens only via RabbitMQ. This is hosted in Lagoon Core, and consumed (and published back to) by Lagoon Remote. This allows Lagoon Remotes to be managed by different teams, in different locations - even behind firewalls or inaccessible from the internet.

Lagoon services are mostly built in Node.js. More recent development occurs in Go, and most of the automation and scripting components are in Bash.

Lagoon Core

All the services that handle the API, authentication and external communication are installed here. Installation is via a [Helm Chart].(

  • API
    • api (the GraphQL API that powers Lagoon)
    • api-db (the MariaDB storage for the API)
    • api-redis (the cache layer for API queries)
  • Authentication
    • keycloak (the main authentication application)
    • keycloak-db (the MariaDB storage for Keycloak)
    • auth-server (generates authentication tokens for Lagoon services)
    • ssh (provides developers with ssh access to the sites hosted on Lagoon)
  • Messaging
    • broker (the RabbitMQ message service used to communicate with Lagoon Remote)
    • webhooks2tasks (the service that converts incoming webhooks to API updates)
    • actions-handler (the service that to manage bulk action processing for builds and tasks)
  • Webhooks
    • webhook-handler (the external service that Git Repositories and Registries communicate with)
    • backup-handler (the service used to collect and collate information on backups)
  • Notifications
    • logs2notifications (the service that pushes build notifications to a configured notification types)

Lagoon Remote

All the services that are used to provision, deploy and maintain sites hosted by Lagoon on Kubernetes live here. These services are mostly comprised of third-party tools, developed external to Lagoon itself. Installation is via a Helm Chart

  • Docker Host (the service that stores and caches upstream docker images for use in builds)
  • Storage Calculator (an optional service to collect the size of storage and databases)
  • Remote Controller (the controllers that handle building and deploying sites onto Lagoon)
  • Build Deploy Tool (the service that computes which services, configuration and settings to provision for Kubernetes)
  • Aergia (an optional controller that can idle non-production sites not currently in use to conserve resources)
  • Dioscuri (an optional operator that provides Active/Standby functionality to Lagoon)
  • DBaaS Operator (an optional operator that provisions databases from an underlying managed database)

Lagoon UI

  • ui (the main user interface and dashboard for Lagoon, usually installed in lagoon-core, but can also be installed anywhere as a Lagoon project)

Lagoon Tools

  • lagoon-cli (the command-line interface for managing sites on Lagoon)
  • lagoon-sync (a command-line interface for syncing databases or file assets between Lagoon environments)
  • drush-alias (provides Drupal developers with an automated alias service for Drush)

Additional Services

These services are usually installed alongside either Lagoon Core or Lagoon Remote to provide additional functionality to Lagoon.


Lagoon has a comprehensive test suite, designed to cover most end-user scenarios. The testing is automated in Ansible, and runs in Jenkins, but can also be run locally in a self-contained cluster. The testing provisions a standalone Lagoon cluster, running on Kind (Kubernetes in Docker). This cluster is made of Lagoon Core, Lagoon Remote, an image registry and a set of managed databases. It runs test deployments and scenarios for a range of Node.js, Drupal, Python and NGINX projects, all built using the latest Lagoon images.

Other Lagoon components

Here are a number of other repositories, tools and components used in Lagoon

These images are used by developers to build web applications on, and come preconfigured for running on Lagoon as well as locally. There are php, NGINX, Node.JS, Python (and more) variants. These images are regularly updated, and are not only used in hosted projects, they're used in Lagoon too!

To browse the full set of images, head to

A meta-project that houses a wide range of example projects, ready-made for use on Lagoon. These projects also include test suites that are used in the testing of the images. Please request an example via that repository if you want to see a particular one, or even better, have a crack at making one!

Houses all the Helm Charts used to deploy Lagoon, it comes with a built-in test suite.

To add the repository helm repo add lagoon has developed a number of tools, charts and operators designed to work with Lagoon and other Kubernetes services.

To add the repository helm repo add lagoon


Do you want to contribute to Lagoon? Fabulous! See our Documentation on how to get started.


Lagoon was originally created and open sourced by the team at in August 2017, and powers their global hosting platform.


Find more information about Lagoon:

At our website -

In our documentation -

In our blog -

Via our socials -

On Discord -