Install Lagoon on OpenShift

Lagoon is not only capable of deploying into OpenShift, it actually runs in OpenShift. This creates the just tiny chicken-egg problem of how to install Lagoon on an OpenShift when there is no Lagoon yet. 🐣

Luckily, we can use the local development environment to kickstart another Lagoon in any OpenShift, running somewhere in the world.

Check the OpenShift Requirements before continuing.

This process consists of 4 main stages::

  1. Configure existing OpenShift.
  2. Configure and connect local Lagoon with OpenShift.
  3. Deploy!
  4. Configure Installed Lagoon.

Configure existing OpenShift


This also works with the OpenShift provided via MiniShift that can be started via make minishift.

In order to create resources inside OpenShift and push into the OpenShift Registry, Lagoon needs a Service Account within OpenShift (read more about Service Accounts).

Technically, Lagoon can use any Service Account and also needs no admin permissions. The only requirement is that the self-provisioner role is given to the Service Account.

In this example we create the Service Account lagoon in the OpenShift Project default.

  1. Make sure you have the oc cli tools already installed. If not, please see here.
  2. Log into OpenShift as an admin:

oc login <openshift console>

  1. Run the openshift-lagoon-setup script

make openshift-lagoon-setup

  1. At the end of this script it will give you a serviceaccount token. Keep that somewhere safe.

Configure and connect local Lagoon with OpenShift

In order to use a local Lagoon to deploy itself on an OpenShift, we need a subset of Lagoon running locally. We need to teach this local Lagoon how to connect to the OpenShift:

  1. Edit lagoon inside local-dev/api-data/01-populate-api-data.gql, in the Lagoon Kickstart Objects section:
  2. [REPLACE ME WITH OPENSHIFT URL] - The URL to the OpenShift Console, without console at the end.
  3. [REPLACE ME WITH OPENSHIFT LAGOON SERVICEACCOUNT TOKEN] - The token of the lagoon service account that was shown to you during make openshift-lagoon-setup.
  4. Build required images and start services:

make lagoon-kickstart

This will do the following:

  1. Build all required Lagoon service images (this can take a while).
  2. Start all required Lagoon services.
  3. Wait 30 secs for all services to fully start.
  4. Trigger a deployment of the lagoon sitegroup that you edited, which will cause your local lagoon to connect to the defined OpenShift and trigger a new deployment.
  5. Show the logs of all local Lagoon services.

  6. As soon as you see messages like Build lagoon-1 running in the logs, it's time to connect to your OpenShift and check the build. The URL you will use for that depends on your system, but it's probably the same as in openshift.console.

  7. Then you should see a new OpenShift Project called [lagoon] develop , and in there a Build that is running. On a local OpenShift you can find that under
  8. If you see the build running, check the logs and see how the deployment system does its magic! This is your very first Lagoon deployment running! 🎉 Congrats!
  9. Short background on what is actually happening here:
  10. Your local running Lagoon (inside docker-compose) received a deploy command for a project called lagoon that you configured.
  11. This project has defined to which OpenShift it should be deployed (one single Lagoon can deploy into multiple OpenShifts all around the world).
  12. The local running Lagoon service openshiftBuildDeploy connects to this OpenShift and creates a new project, some needed configurations (ServiceAccounts, BuildConfigs, etc.) and triggers a new build.
  13. This build will run and deploy another Lagoon within the OpenShift it runs.
  14. As soon as the build is done, go to the Application > Deployments section of the OpenShift Project, and you should see all the Lagoon DeploymentConfigs deployed and running. Also go to Application > Routes and click on the generated route for ui (for a local OpenShift this will be, if you get the Lagoon UI as result, you did everything correct, bravo! 🏆


Once Lagoon is install operational, you need to initialize OpendistroSecurity to allow Kibana multitenancy. This only needs to be run once in a new setup of Lagoon.

  1. Open a shell of an Elasticsearch pod in logs-db.
  2. run ./

Configure Installed Lagoon

We have a fully running Lagoon. Now it's time to configure the first project inside of it. Follow the examples in GraphQL API.