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

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:

• Locally (for evaluation, testing, debugging or development) using Helm charts and kind
• Into your managed Kubernetes cloud provider of choice - it's running in production on Amazon Elastic Kubernetes Service, Azure Kubernetes Service, and Google Kubernetes Engine, but we are confident that it will also run on any other managed Kubernetes service.

For more information on developing or contributing to Lagoon, head to https://docs.lagoon.sh/contributing-to-lagoon

For more information on installing and administering Lagoon, head to https://docs.lagoon.sh/administering-lagoon

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.

All the services that handle the API, authentication and external communication are installed here. Installation is via a [Helm Chart].(https://github.com/uselagoon/lagoon-charts/tree/main/charts/lagoon-core)

• 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)
  • controllerhandler (the service that relays build progress from the controllers)
  • logs2s3 (the service that collects build logs and sends them to an S3-compatible back end)
• 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
  • logs2email (the service that pushes build notifications to a nominated email address)
  • logs2slack (the service that pushes build notifications to a nominated Slack (or Discord) channel)
  • logs2rocketchat (the service that pushes build notifications to a nominated Rocket Chat channel)
  • logs2microsoftteams (the service that pushes build notifications to a nominated Microsoft Teams channel)
  • logs2webhook (the service that pushes build notifications to a nominated webhook endpoint)
• Other Services
  • ui (the main user interface and dashboard for Lagoon)
  • 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)

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

• Remote Controller (the controllers that handle building and deploying sites onto Lagoon)
• kubectl-build-deploy (the service that computes which services, configuration and settings to provision for Kubernetes)
• docker-host (the service that stores and caches upstream docker images for use in builds)
• lagoon-idler (an optional operator 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)

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

• Registry (required)

  • Harbor (provides image registry services to Lagoon projects)
  • Trivy (scans images for vulnerability, and can report to Lagoon)

• Lagoon Logging (optional)

  • lagoon-logging (utilizes banzaicloud/logging-operator to collect and augment container&router logs from all sites, and sends them to a logs-dispatcher)
  • logs-dispatcher (collects application logs from sites, as well as container&router logs from lagoon-logging, enriches them with additional metadata and sends them to a central log concentrator)
  • lagoon-logs-concentrator (collects logs from remote logs-dispatchers and sends them to Elasticsearch)

• Open Policy Agent (optional)

  • lagoon-gatekeeper (centralized policy library for Lagoon)

• Elasticsearch or Opensearch (optional)

  • Open Distro for Elasticsearch (provides centralized log storage, search and analysis)
  • Kibana (the default user interface for Elasticsearch searching and visualization)

• Managed databases, for use with DBaaS operator (optional)

  • MariaDB (self managed or via Amazon RDS for MariaDB, Azure Database for MariaDB
  • MySQL (self managed or via Amazon RDS for MySQL, Amazon Aurora MySQL, Azure Database for MySQL, Cloud SQL for MySQL)
  • PostgreSQL (self managed or via Amazon RDS for PostgreSQL, Amazon Aurora PostgreSQL, Azure Database for PostgreSQL, Cloud SQL for PostgreSQL )
  • MongoDB (self managed, or via Amazon DocumentDB, Azure Cosmos DB )

• Backups (optional)

  • k8up (provides a scheduled backup and prune service to environment namespaces)

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.

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 https://hub.docker.com/u/uselagoon

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 https://uselagoon.github.io/lagoon-charts/

amazee.io 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 https://amazeeio.github.io/charts/

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 amazee.io in August 2017, and powers their global hosting platform.

Find more information about Lagoon:

At our website - https://lagoon.sh

In our documentation - https://docs.lagoon.sh

In our blog - https://dev.to/uselagoon

Via our socials - https://twitter.com/uselagoon