Learning objectives

In this tutorial, learn how to create, edit, build, and deploy a simple “Hello World” Lagom application with Microclimate.


Lagom is an open source framework that helps you create microservices, bringing them together into systems while you move away from the monolith. It has reactive qualities at its core, being based on the Play framework and the Akka toolkit, it helps you build a responsive user experience, with resilience to failures, and elasticity under load. This means making best use of modern computing environments and meeting demanding user expectations. Lagom, Play, and Akka are all part of the Reactive Platform from Lightbend and IBM. The Lagom framework home page has some short videos describing it in more detail.

Microclimate, is an end to end development environment that lets you rapidly create, edit, and deploy applications to Kubernetes. In particular IBM Cloud Private – IBM’s Kubernetes platform. With Microclimate, applications are run in containers from the start and can be delivered into production on Kubernetes through an automated DevOps pipeline using Jenkins. Microclimate currently supports Go, Java, Node.js, Python and Swift.

Starting with the October 2018 release of Microclimate, we have added the option to create a Java based Lagom application. This gives you a project structure to expand and build on. Of course, you can edit your service in all the ways that Microclimate supports, using its browser-based editor or your favourite IDE.

From Microclimate, with just a few clicks, you can setup a Jenkins pipeline in IBM Cloud Private to build the application. The starter project includes a Jenkinsfile to enable this. Also in the application is a Helm chart, which the final stage of the pipeline uses to deploy a successfully built application.


Step 1. Install Microclimate

Microclimate can be installed locally on your laptop and into an installation of IBM Cloud Private. If you’re just going to install locally, you’ll be able to create projects, then build and run them on your laptop. To run a Jenkins pipeline and have it deploy the application there, you’ll need to install Microclimate into IBM Cloud Private as well.

Follow the instructions on the Microclimate “Getting started” page.

Step 2. Start Microclimate

  1. After installation, start Microclimate using the following command:

    ~/mcdev start -o

    This will open the front page in your browser:


  2. Click the New Project button.

  3. Select the Java language tile, enter a name for your project, and click Next.


  4. Select Lagom, and then click Create.


    The project’s overview page is shown, and a local build is started.


After the build completes, the application status will be “Running,” and the application URL is displayed. Click the link, and you’ll be taken to the running application.


You can change the URL to display words other than “world.”

Okay, it’s simple – that’s the point. It’s just enough to get you started with writing a Lagom application.

Step 3. IBM Cloud Private for build pipeline and deploy

You now have a git repository stored locally. In order to have the pipeline build it, you need to push it to a remote repository.

  1. Create a new repo in GitHub.


  2. Switch back to the Microclimate browser tab, and click the Edit Code icon.

    You’ll see a command line window embedded in the browser.

  3. Change directory to the project you’ve created (ours is called lagomtest):

    cd lagomtest
  4. Add a git remote to the project:

    git remote add origin https://github.com/<your github id>/lagomtest.git
  5. Push the repository to GitHub:

    git push -u origin master

At this point, I always like to check through the GitHub UI that my code has been pushed.

Step 4. Create the pipeline

  1. Switch to the Microclimate pipeline view.


  2. Click Create pipeline, then follow the stages to create a pipeline:

    1. Give it a name.

    2. Enter the Git URL from the previous step.

    3. Enter the address of the Microclimate instance on IBM Cloud Private, which takes the form: https://microclimate.<IP address>.nip.io

  3. When it’s finished, click the Open pipeline button, and you’ll be taken to the Jenkins instance through the IBM Cloud Private login page.


    You’ll see that Jenkins has already started to fetch the code from GitHub and is building it.

  4. Click the master branch, and you’ll see the progress of the build.


Step 5. Configure the automated application deploy

  1. When it has finished, switch back to the Microclimate tab.

  2. Click the Add deployment button.


  3. Keep the defaults, and click Save.


  4. Switch back to the Jenkins browser tab, and you’ll see a new build has started.


    Once this build is done, the application will have been deployed into IBM Cloud Private (ICP).

  5. Switch to ICP, and find the “Deployments” page.


    The newest deployment in the list will be for the application deployed from Jenkins.

  6. Click it to bring up the Overview page.


    From there you will find the NodePort for the application. This is the port on which ICP has exposed the application. Setting up Ingress is out of the scope of this article.

  7. Now you can bring up a browser tab and visit the starter application.


    The same application you had running in a Docker container on your laptop is now running in IBM Cloud Private.


In this tutorial, you’ve seen how you to install Microclimate and create a simple Reactive Platform application that makes use of the Lagom framework. You have run it in a Docker container on your laptop and, with a few clicks, created a pipeline in IBM Cloud Private, which you then set up to deploy the application whenever it successfully builds.