Welcome to Lagoon Documentation
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.
- 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
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
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
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.
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.
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.