docker-compose.yml file is used by Lagoon to:
Learn which services/containers should be deployed.
Define how the images for the containers are built.
Define additional configurations like persistent volumes.
Docker-compose (the tool) is very strict in validating the content of the YAML file, so we can only do configuration within
labels of a service definition.
Here a straightforward example of a
docker-compose.yml file for Drupal:
version: '2.3'x-lagoon-project:# Lagoon project name (leave `&lagoon-project` when you edit this)&lagoon-project drupal-examplex-volumes:&default-volumes# Define all volumes you would like to have real-time mounted into the docker containersvolumes:- .:/app:delegatedx-environment:&default-environmentLAGOON_PROJECT: *lagoon-project# Route that should be used locally, if you are using pygmy, this route *must* end with .docker.amazee.ioLAGOON_ROUTE: http://drupal-example.docker.amazee.io# Uncomment if you like to have the system behave like in production#LAGOON_ENVIRONMENT_TYPE: production# Uncomment to enable xdebug and then restart via `docker-compose up -d`#XDEBUG_ENABLE: "true"x-user:&default-user# The default user under which the containers should run. Change this if you are on linux and run with another user than id `1000`user: '1000'services:nginx:build:context: .dockerfile: nginx.dockerfilelabels:lagoon.type: nginx-php-persistentlagoon.persistent: /app/web/sites/default/files/php:build:context: .dockerfile: php.dockerfilelabels:lagoon.type: nginx-php-persistentlagoon.name: nginxlagoon.persistent: /app/web/sites/default/files/mariadb:image: amazeeio/mariadb-drupallabels:lagoon.type: mariadb
This is the machine name of your project, define it here. We’ll use “drupal-example.”
This tells Lagoon what to mount into the container. Your web application lives in
/app, but you can add or change this if needed.
Here you can set your local development url. If you are using pygmy, it must end with
If you want to exactly mimic the production environment, uncomment
If you want to enable xd-ebug, uncomment
You are unlikely to need to change this, unless you are on Linux and would like to run with a user other than
This defines all the services you want to deploy. Unfortunately,
docker-compose calls them services, even though they are actually containers. Going forward we'll be calling them services, and throughout this documentation.
The name of the service (
mariadb in the example above) is used by Lagoon as the name of the Kubernetes pod (yet another term - again, we'll be calling them services) that is generated, plus also any additional Kubernetes objects that are created based on the defined
lagoon.type, which could be things like services, routes, persistent storage, etc.
If you want Lagoon to build a Dockerfile for your service during every deployment, you can define it here:
The build context path that should be passed on into the
docker build command.
Location and name of the Dockerfile that should be built.
If you don't need to build a Dockerfile and just want to use an existing Dockerfile, define it via
Lagoon needs to know what type of service you are deploying in order to configure the correct Kubernetes and OpenShift objects.
This is done via the
lagoon.type label. There are many different types to choose from. Check Service Types to see all of them and their additional configuration possibilities.
If you'd like Lagoon to ignore a service completely - for example, you need a container only during local development - give it the type
Some containers need persistent storage. In many cases, Lagoon knows where that persistent storage needs to go. For example, for a MariaDB container, Lagoon knows that the persistent storage should be put into
/var/lib/mysql , and puts it there automatically without any extra configuration to define that. For some situations, though, Lagoon needs your help to know where to put the persistent storage:
lagoon.persistent - The absolute path where the persistent storage should be mounted (the above example uses
/app/web/sites/default/files/ which is where Drupal expects its persistent storage).
lagoon.persistent.name - Tells Lagoon to not create a new persistent storage for that service, but instead mounts the persistent storage of another defined service into this service.
lagoon.persistent.size - The size of persistent storage you require (Lagoon usually gives you minimum 5G of persistent storage, if you need more, define it here).
lagoon.persistent.class - By default Lagoon automatically assigns the right storage class for your service (like SSDs for MySQL, bulk storage for Nginx, etc.). If you need to overwrite this, you can do so here. This is highly dependent on the underlying Kubernetes/OpenShift that Lagoon runs on. Ask your Lagoon administrator about this.
Kubernetes and OpenShift don't deploy plain containers. Instead, they deploy pods, with each one or more containers. Usually Lagoon creates a single pod with a container inside for each defined
docker-compose service. For some cases, we need to put two containers inside a single pod, as these containers are so dependent on each other that they should always stay together. An example for such a situation is the PHP and Nginx containers that both contain PHP code of a web application like Drupal.
For these cases, it is possible to tell Lagoon which services should stay together, which is done in the following way (remember that we are calling containers
services because of
Define both services with a
lagoon.type that expects two services (in the example this is
nginx-php-persistent defined on the
Link the second service with the first one, defining the label
lagoon.name of the second one with the first one. (in the example this is done with defining
This will cause Lagoon to realize that the
php containers are combined in a pod that will be called
Lagoon still needs to understand which of the two services is the actual individual service type (
php in this case). It does this by searching for service names with the same name that are given by the type, so
nginx-php-persistent expects one service with the name
nginx and one with
php in the
docker-compose.yml. If for any reason you want to use different names for the services, or you need for than one pod with the type
nginx-php-persistent there is an additional label
lagoon.deployment.servicetype which can be used to define the actual service type.
nginx:build:context: .dockerfile: nginx.dockerfilelabels:lagoon.type: nginx-php-persistentlagoon.persistent: /app/web/sites/default/files/lagoon.name: nginx # If this isn't present, Lagoon will use the container name, which in this case is nginx.lagoon.deployment.servicetype: nginxphp:build:context: .dockerfile: php.dockerfilelabels:lagoon.type: nginx-php-persistentlagoon.persistent: /app/web/sites/default/files/lagoon.name: nginx # We want this service be part of the nginx pod in Lagoon.lagoon.deployment.servicetype: php
In the example above, the services are named
php (but you can call them whatever you want). The
lagoon.name tells Lagoon which services go together - all of the services with the same name go together.
In order for Lagoon to realize which one is the
nginx and which one is the
php service, we define it via
lagoon.deployment.servicetype: nginx and
OpenShift defines templates as follows:
A template describes a set of objects that can be parameterized and processed to produce a list of objects for creation by OpenShift Container Platform. A template can be processed to create anything you have permission to create within a project, for example services, build configurations, and DeploymentConfigs. A template may also define a set of labels to apply to every object defined in the template.
Lagoon comes with a variety of pre-defined templates, which set all kinds of needed configuration in YAML files. Check out the shipped templates from the templates folder of
If you need to make changes to the OpenShift templates, you can define your own template via
You can also overwrite the templates for a specific environment. This is done in
By default , Lagoon expects that services from custom templates are rolled out via a
DeploymentConfig object within Openshift/Kubernetes. It monitors the rollout based on this object. In some cases, the services that are defined via custom deployment need a different way of monitoring. This can be defined via
deploymentconfig - This is the default. Expects a
DeploymentConfig object in the template for the service.
statefulset - Expects a
Statefulset object in the template for the service.
daemonset - Expects a
Daemonset object in the template for the service.
false - Will not monitor any rollouts, and will just be happy if the template applies and does not throw any errors.
You can also overwrite the rollout for just one specific environment. This is done in
Feeling adventurous and want to do something completely customized? Welcome to the Danger Zone!
When defining a service as
lagoon.type: custom, you can tell Lagoon to not use any pre-defined service type templates and pass your full own custom YAML file.
This also expects the label
lagoon.template to be defined with the path to the YAML file where you define all the needed Kubernetes objects to be executed. In here you can define your own OpenShift templates like the ones in the templates folder of