Welcome to Lagoon Documentation

Version 2.22

What is Lagoon?

Lagoon is an open-source application delivery platform designed for Kubernetes and OpenShift. It solves what developers dream about: a system that allows developers to locally develop their code and services with Docker and run the exact same system in production. The same container images, service configurations, and code can be used across environments, making deployment seamless and consistent.

Key Benefits

Same docker images in development and production
No need for developers to understand Kubernetes
Automated deployments via Git integration
Handles complex workloads like CMS and LMS applications
Horizontally scalable for high-traffic applications

Architecture

Core Components

Lagoon is built on a microservices architecture, allowing for flexibility and scalability. It uses Docker containers to encapsulate applications and their dependencies, ensuring consistency across environments.

Lagoon comprises two main components:

Lagoon Core: The central management component including API server, UI, and message queue
Lagoon Remote: The deployment environment component that handles builds and runtime operations

These can be installed in separate Kubernetes clusters for enhanced security, with all inter-cluster communication happening via RabbitMQ. A single Lagoon Core installation can serve multiple Remotes, creating a flexible and secure architecture.

Most Lagoon services are built in Node.js, with more recent development occurring in Go, and automation/scripting components written in Bash.

Build and Deploy Process

Lagoon follows a comprehensive process when deploying applications:

Sets up the OpenShift project/Kubernetes namespace for the environment
Reads your docker-compose.yml file to understand service configuration
Builds Docker images for each service defined
Configures Kubernetes or OpenShift services and routes
Pushes and tags images to the registry
Sets up persistent storage for services that need it
Configures cron jobs as needed
Runs defined pre-rollout tasks
Creates Deployments, Statefulsets, or Daemonsets based on service types

The Lagoon deployment workflow consists of these steps:

Git Push

Developer pushes code to Git repository

Webhook Trigger

Git provider sends webhook to Lagoon

Build Process

Lagoon builds Docker images

Deployment

Images are deployed to the environment

Example Configuration

# .lagoon.yml file example
docker-compose-yaml: docker-compose.yml

environments:
  main:
    routes:
      - nginx:
          - example.com
    cronjobs:
      - name: drush cron
        schedule: "*/15 * * * *"
        command: drush cron
        service: cli

This configuration specifies how Lagoon should handle the "main" environment, including which routes to expose and what cronjobs to configure.

Use Cases

Drupal at Scale

Lagoon excels at hosting Drupal websites and can handle high-traffic scenarios:

Runs Drupal with Varnish, NGINX, PHP, MariaDB, Solr, Redis, and more in separate containers
Enables decoupled Drupal setups with Node.js running alongside regular Drupal containers
Manages cache tags across all cache layers for optimal performance
Creates individual environments for each git branch or pull request for better testing
Successfully handles sites with 110+ million page hits per month

Success Story: Australian Government

Multiple Australian Government websites run on Lagoon-powered Drupal infrastructure, handling millions of visitors during peak events like elections and emergency announcements.

Development Workflow

Developers can work locally with Docker and have the exact same setup in production
Simple deployment: just push to your Git repository and Lagoon handles the rest
Uses Alpine Linux for container installs from Docker images to optimize size
Integrates with tools like Ansible, Jenkins, TravisCI, and CircleCI for configuration management

# Local development command example
docker-compose up -d
# Make changes to your code
git commit -am "Made some changes"
git push # Lagoon handles the rest!

Frequently Asked Questions

What makes Lagoon different from other deployment solutions?

Lagoon distinguishes itself from other deployment solutions through its unique approach of using the same Docker setup across local development and production environments. This eliminates the "it works on my machine" problem. Additionally, Lagoon is specifically optimized for CMS platforms like Drupal and WordPress, offering specialized features for these workloads while maintaining flexibility for other application types.

Does Lagoon support multi-cluster deployments?

Yes, Lagoon supports multi-cluster deployments through its Core/Remote architecture. A single Lagoon Core can manage multiple Remote installations, allowing for deployments across different regions, cloud providers, or infrastructure configurations. This enables high availability and geographic distribution of workloads.

Can I deploy Lagoon on any Kubernetes cluster?

Lagoon is designed to work with any Kubernetes-compliant cluster as well as OpenShift. The recommended minimum Kubernetes version is 1.20+. While Lagoon does not require any special cloud provider features, it can leverage specific capabilities when available for enhanced functionality.