IBM microservicesWhen I started building my first application based on a Microservice Architecture pattern, I knew about the basic idea of microservices and I knew about writing code. So I was confident developing microservice applications, but I knew very little about things like project management and build automation or container deployment and orchestration. Technologies and considerations that are more important for the operations part of DevOps. Using Microclimate, a development environment that integrates the writing and containerized deployment of microservices, helped me get started quickly with development by taking care of many of the basic aspects of deployment. If you are in a similar situation to mine, then Microclimate might be exactly the tool you are looking for to get started with microservices.

What I Wish I Knew about Microservices Application Deployment

Microclimate is a great tool for beginners looking to start developing and deploying microservice-based applications, because it lowers the barrier to entry by automating many of the tasks that require in-depth domain-specific knowledge beyond writing application code. Things like creating and deploying a Docker container for a project or creating a Maven project that builds a Liberty server instance. This saves developers a lot of time up front, because they can focus on their specific application without the need to become an expert in all of those areas. Still, there is some basic knowledge of each area that can be helpful, since more complex applications may require a degree of customization. The rest of this post describes what I wish I knew when I started working with Microclimate.

Docker and Docker-Compose

Docker is the central technology on which Microclimate runs. When Microclimate starts, it starts three Docker containers that work together to provide the functionality of Microclimate:

microclimate-file-watcher: This container tracks the files of Microclimate projects, so that projects are stopped, rebuilt, and restarted whenever changes to those files are saved. The user has no ability to manually start, stop, or build applications, so the only way to trigger a rebuild or restart of the application is to save a change to some file. Sometimes, for example, a build error occurs that is unrelated to the application. It is then necessary to make a change like adding or removing an empty line to trigger a rebuild that will successfully restart the application. There is also an important distinction between rebuilds that only re-compile the application, which happen if the changes occur in the application-specific files like the src/main/java classes, and those that also restart the server, which will happen when you change certain server configuration files like server.xml. If you make a change in configuration, like an edit to the server.env file, it will only be incorporated when the server restarts, so you may need to save a change (adding or removing a blank line is enough) in server.xml for the rebuild to have the desired effect.

microclimate-theia: This container runs the in-browser IDE provided by Microclimate, which is based on the Theia IDE. You can also import Microclimate projects into your own preferred IDE (I would recommend this), and the file-watcher will still monitor the changes and rebuild the projects upon saved changes as described above.

microclimate-portal: This container runs the Microprofile user interface, which will be hosted locally on port 9090 (http://localhost:9090/). The user interface allows you to create, delete, view, and monitor all of your Microclimate projects and their statuses, build logs, and application logs. You can also edit code in the portal using the Theia IDE. Sometimes there is an error where the network connection is lost from the portal, which can be fixed by restarting Microclimate.

In addition to these three containers, Docker images are made for each new project when it is created and Microclimate starts containers from these images. These containers host the applications for each project when Microclimate is run and stops the containers when Microclimate is stopped.

All in all, Microclimate takes care of almost everything involving Docker, but it can be helpful to know the basics to understand what is going on in the background. Introductory tutorials on Docker are easy to find just by searching the web, and there is a tutorial series specifically on using Docker with Liberty here.

Maven projects for WebSphere Liberty

Maven is the tool that takes your application code and server configuration files and compiles, packages, and installs them into an executable application running on an actual Liberty instance. The basics of creating a Maven project with that functionality is taken care of when a new Microclimate project is created. So the main things to keep in mind for developers with limited Maven experience are the following:

1. The configuration of a Maven project is all described in a file called pom.xm so if you want or need to make changes, that is the place to do it.

2. Maven can be used to download and install dependencies for your application in the section of pom.xml.

3. Maven can be instructed to perform certain tasks, copying files to a specific location, for example, in the plug-ins section of pom.xml.

Most applications will probably need to at least use Maven to install a dependency, but this is a pretty user-friendly process and finding exact syntax for the format of listing a given dependency tends to be a simple process.

WebSphere Liberty server runtime

Liberty is the IBM server runtime environment that Microclimate uses to actually host the applications built as Microclimate projects. Most projects will involve some customization of the configuration of the Liberty environment (much of which takes place in the server.xml file), but documentation on customizing and configuring Liberty is widely available. IBM Knowledge Center and the Open Liberty guides are good places to start when looking to implement a certain feature or find an answer to questions about Liberty. The key thing to remember is that your Microclimate projects are not themselves Liberty instances; they are compiled and packaged into Liberty instances, so when following a tutorial, certain configuration files will not be in the same location in the project structure as they would be in a Liberty instance. Instead, they will need to be either placed in the correct directory of the project or they will need to be specifically addressed in the pom.xml so that Maven will copy them to the correct location when the Liberty instance is created during the project build. This will be addressed more in depth in the next section.

Bringing it all Together: A New Microclimate Project

As a disclaimer, my work with Microclimate thus far has focused on Java projects build with Eclipse Microprofile/Java EE, and I have been working locally not on IBM Cloud Private. So this section will focus on that specific environment and leave out of a discussion of some of the files and directories that seem to be for that purpose.

The structure described below gives a tour of the default application that is generated when a new Eclipse Microprofile/Java EE project is created.

The main project directory, which you can find as the directory that shares the name of the project either on the built-in Theia editor or in the microclimate-workspace directory on your local machine, is full of configuration files and directories, most of which you do not need to worry about. Although, note that this is where pom.xml is located. The two directories we will focus on in the main project directory are the two most important directories for developing the application: src and mc-target.


This is the directory where you will spend the most time. All of your application code, including Java code, tests, and Liberty configuration files are all located here.

The initial directory is as follows:

Directory or File Description
src/ The root directory.
+- main/ The application code.
    +- java/ Java classes.
        +- application/ Application package.
            +- rest/ REST classes.
                +- v1/ Version 1.
                    +- The example application that is generated when the project is created. Provides the endpoint “localhost:{port}/{contextroot}/v1/example”.
                +- The root of the JAX-RS application. This class extends
                +- Provides an endpoint for the context root (“localhost:{port}/{contextroot}). There are two conflicting methods for HTTP GET requests in this class, so you will get a warning about that in the Application Logs until you delete one of them.
            +- HealthEndpoint Provides an endpoint at “localhost:{port}/{contextroot}/health that responds with “{status:UP}” when the application is running. Note: This does not use the Eclipse Microprofile Health feature (mpHealth).
    +- liberty/ Liberty server runtime files.
        +- config/ Liberty configuration files. See more about the specific configuration files here. Note: One of the standard Liberty config files, is not in this folder, but is defined in the pom.xml file under the <bootstrapProperties> tag and created by Maven when the Liberty instance (mc-target) is created.
            +- jvm.options A system property configuration file.
            +- jvmbx.options A system property configuration file.
            +- server.env An environment variable configuration file for the server.
            +- server.xml The key Liberty configuration file.
    +- resources/ Additional resources outside of code and server configuration that the app might need. You can use Maven to copy files from this directory into the necessary location in the Liberty instance (mc-target).
        +- index.html A default HTML homepage for the example.
    +- webapp/ Web-related files.
        +- WEB-INF/ Web-related configuration for the app.
            +- beans.xml Configuration file for defining Java beans.
            +- ibm-web-ext.xml Defines the context root for the web application.
+- test/ Test files.
     +- java/ Java classes for tests.
         +- it/ Integration tests.
            +- An example integration test generated by default.


This is the directory with the actual Liberty instance compiled, packaged, and installed by Maven. The Liberty directory structure is found in the liberty directory and is described in detail here. The compiled application from the project is packaged as a WAR file and ZIP file under the name project-1.0-SNAPSHOT.

Join The Discussion

Your email address will not be published. Required fields are marked *