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.
Lagoon only reads the labels, service names, image names and build definitions from a
docker-compose.yml file. Definitions like: ports, environment variables, volumes, networks, links, users, etc. are IGNORED. This is intentional as the
docker-compose file is there to define your local environment configuration. Lagoon learns from the
lagoon.type the type of service you are deploying and from that knows about ports, networks and any additional configuration that this service might need.
Here is a straightforward example of a
docker-compose.yml file for Drupal:
services: nginx: build: context: . dockerfile: nginx.dockerfile labels: lagoon.type: nginx-php-persistent lagoon.persistent: /app/web/sites/default/files/ php: build: context: . dockerfile: php.dockerfile labels: lagoon.type: nginx-php-persistent lagoon.name: nginx lagoon.persistent: /app/web/sites/default/files/ mariadb: image: amazeeio/mariadb-drupal labels: lagoon.type: mariadb
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
- Location and name of the Dockerfile that should be built.
Lagoon does NOT support the short version of
build: <Dockerfile> and will fail if it finds such a definition.
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 - just 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.typethat expects two services (in the example this is
nginx-php-persistentdefined on the
- Link the second service with the first one, defining the label
lagoon.nameof 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.dockerfile labels: lagoon.type: nginx-php-persistent lagoon.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: nginx php: build: context: . dockerfile: php.dockerfile labels: lagoon.type: nginx-php-persistent lagoon.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
If you need to make changes to the OpenShift templates, you can define your own template via
lagoon.template. Check out the shipped templates from the templates folder of
The template is called with
oc process, so you should define the same parameters as seen in the default templates.
You can also overwrite the templates only for a specific environment. This is done in
Custom Rollout Monitor Types¶
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
DeploymentConfigobject in the template for the service.
statefulset- Expects a
Statefulsetobject in the template for the service.
daemonset- Expects a
Daemonsetobject 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
The template is called with
oc process, so you should define the same parameters as in the default templates.