Being an eMobility leader in various projects across multiple startups, Piotr was responsible for OCPI and OCPP integration as well as EMP and CPO platforms development. With extensive expertise in the open standards field and eMobility tech solutions, he is leading teams of experienced developers and contributing with invaluable knowledge and experience.

Piotr Majcher

Hexagonal architecture is nothing new. We can achieve its main principle by using basic language mechanisms and a proper package structure. On top of that, it’s relatively cheap to do that. Especially when we compare it to the cost of the potential technical debt that might appear because we failed to follow good practices when developing our IT project. Still, hexagonal architecture isn’t a very popular technique today. So, let’s start with some sample legacy code and see how we could refactor it to follow the hexagonal architecture principles.

Note: In this example, we use Java and Spring but this technique is language and framework agnostic.

From plain old sample project to Hexagonal Architecture

To make our sample project simpler, let’s assume that we’re developing an application that processes a single resource - messages. We’re exposing one method over HTTP: get all messages. We can start now with the greenfield project that has a well-known structure:

Inside you’ll find some very simple code. Let’s start from the service, our core component:

What’s wrong with that? Our message service uses MessageRepository directly, so it depends on it. It breaks the last SOLID principle - Dependency Inversion. How can we get rid of this dependency? Here’s the answer: we can invert it. Let’s define the interface in a core (service) package.

We can then implement it in the persistence package using files, MongoDB, or any other storage. Now the persistence - the low-level technical component - depends on a high-level abstraction.

What did we just do from the Hexagonal Architecture perspective? We have created a secondary (driven) port - MessageRepository - and a secondary adapter - for instance, MongoMessageRepository. Now persistence depends on the domain, not the other way round. It’s worth mentioning here that MessageRepository acts as Service Provider Interface (SPI).

We already saw the secondary (driven) port and adapter. What about the primary one? The primary (driver) port serves as the definition of API domain exposed by the domain to the external world. In our case, it’s the MessageService. Perhaps MessageFacade sounds better? But the name isn’t that important - rather, it’s the fact that this is the only entry point to the domain. The API is called by the primary adapter - in our sample, the MessageController. To summarize:

The primary port is API and it’s called by the primary adapter.

The secondary port is SPI and it’s implemented by the secondary adapter.

Packages are a powerful feature of Java. The package structure should tell us something about the project. What we can say based on the package structure from picture 1 at a first glance? No more than the fact that we use layered architecture. Let’s take a look at how can we improve it to follow the hexagonal architecture approach:

Now the first meaningful part of the package (skipping the company’s domain and project name) contains information about the main business concept - the message service. At this stage, it’s not important if we have controllers and persistency; these are technical details. Digging deeper, we see two main packages - the domain containing entire logic and adapters; the external components dependent on the domain.

The example showed previously is a bit verbose. If you know which component plays which role, the package structure can be simplified and still provide the separation required by hexagonal architecture.

Keeping the core domain separated is crucial, especially for larger projects. If you’re working on a simple CRUD, perhaps the layered architecture is all you need. On the other hand, the goal of providing hexagonal architecture forces developers to think about the boundaries in the application. And that’s always good. Even if the application they’re working on doesn’t require sophisticated architecture, keeping these concepts in mind is always beneficial in the long-term perspective.

Removing technical debt step by step. Visit Solidstudio blog to read the whole article.

Getting access to Java applications inside Docker.

Docker is a great tool that allows developers not to worry about servers, Ops/DevOps not to think about the servers they maintain. It’s also useful for developers who just want to run dependent components without digging into the details of those dependencies.

But Docker comes at a price. It creates an extra level of abstraction and makes accessing the internals of running code more complicated.

 in an environment that is really close to what we usually have in production.

Introduction - debugging a Java application

In order not to stick to any specific IDE, I’m going to use jdb for debugging. It’s a Java debugger which is a part of jdk. Let’s assume we have an executable fat jar with a Spring Boot application called app.jar.

If we want to run the application without debugging it all we need is:

In order to debug it, we need to add few additional parameters (I’m using a specific setup here):

Since we set the suspend parameter to ‘yes’, the application is hanging waiting for debugger.

In another console we can try to attach the debugger to a running application by using the following command:

After few seconds, we can see all the known logs from Spring:

Attaching the debugger to a Java app running inside Docker container

Now, let’s wrap our sample application and run it inside a Docker container. We can do it manually by using the following Dockerfile:

Then we can add the same debug parameters as previously:

Once we build the image and start the container, we can see the same log as before:

Can we now attach the debugger to the Spring application running inside the Docker? Yes, but first we need to expose port 8000 from the container. For instance, we can run a Docker container with the following command:

Now you should be able to attach the debugger without any problems.

Shell and Exec form of CMD and ENTRYPOINT

CMD and ENTRYPOINT are two commands that may be used to tell Docker what tasks need to be executed when starting the container. Both instructions may be used in two ways:

exec form - <instruction> [<executable>, <param1>, <p>, ...]

For instance, we could rewrite the initial docker file I showed you above using exec from:

It’s a small trap when it comes to passing the debugging parameters to exec form of instruction, as

consists of two separate parameters. To make it work, we need to pass it separately:

It’s important to remember that when working with tools like docker-maven-plugin from Spotify as they use exec form of ENTRYPOINT instruction in their documentation by default and it’s easy to just take “debug string” and pass it as a single parameter.

Summary - how to solve common problems with debugging a Java application on Docker

It’s very easy to connect the debugger to a Java application running inside a Docker container. There are two things we have to remember here:

the exposing port we are going to use for debugging,

properly passing parameters to the JVM, having in mind differences between exec and shell forms of CMD and ENTRYPOINT instructions.

Once we have those two things set up, we can debug our code locally in almost the same environment as the production environment.

Learn the easiest way to debug your Java application by reading this piece of content.

Debugging Java applications running on Docker.

Overview of CI and CD pipelines - why is it so important?

Tomasz Sławiński

With outgrowing technology and amount of services around us manual integration and deployment process is no longer the right approach to build and ship your projects safely. Small and large businesses builds and ships their products more often than it was years ago. It is said that each day there is over a billion builds triggered. Can you imagine each of them started manually? I certainly can’t.

That’s when CI/CD pipelines come handy. CI/CD is a concept of delivering any application to a production environment with safety, speed and reliability and as least as possible impact on the customer side. It can be a manual process but in most cases, it’s fully automized and sometimes it will require pressing just one button in some CI/CD tool’s dashboard.

For any software that is built these days, there should be a CI/CD pipeline that will consist of individual steps responsible for different elements of the integration and deployment process.

When working in teams or even individually it is crucial to know that the code that is getting produced is reliable and stable. That’s where CI practice comes in handy. That’s a part of the CI/CD process which gets triggered each time the developer pushes a code change to the repository. That is when verification of newly created code should happen. It’s responsible for proving that the new code doesn’t break existing functionalities and integrates with current business requirements or alarming developers that there are some issues with it. Thanks to it the developers can take action before the code gets to production. Usually, it consists of two or more steps which are: build the project -> run unit tests -> run integration tests. More sophisticated pipelines would integrate with additional tools (such as SonarQube) in further steps to provide a detailed report on the quality of the code. A best practice is that the CI pipeline is getting triggered whenever any push to the repository happens.

Continuous Delivery is a follow-up of the Continuous Integration step and is responsible for getting the code changes deployed into the live environment. Thanks to this step being after CI we have certainty that the code is in the deployable state even if there were thousands of code commits done by multiple developers. In most cases, CD pipeline will get triggered only when push happens to certain branches (master/develop/tag) but it can vary based on companies' standards. Also in some cases, CD pipeline will be executed automatically or manually.

Nowadays there are numbers of tools that can be used for automated CI/CD process for any software. This can be done in Jenkins, Gitlab CICD, Bitbucket pipelines or if the code is hosted on cloud infrastructure Azure Pipelines, AWS Code Build and Code deploy or Code Pipeline. Most of those tools have numerous plugins and integrates with currently used project management tools. When all of that is properly configured life of any person involved in the development becomes much simpler as those plugins are capable of relating code commits with tasks in a way that the whole development history can be accessed from one place.

Let’s get some hands-on CI/CD process. Let’s say that you’ve been asked to set up CI/CD pipeline for a corporation that has several microservices that integrates with other various products and you are responsible for preparing CI/CD pipeline for one backend microservice written in 

How should then such pipeline look like? Let’s have a look at some most popular approaches here:

For this use case, we will be using GitLab CI and will focus only on the account microservice and has pom configured with appropriate execution goals. It’s a quite popular tool these days especially because it comes along with the GitLab repository and the CI/CD pipeline configuration sits within the project code in .gitlab-ci.yml file.

For this case we want that CI pipeline consist of three steps:

So how can we achieve it with GitLab CI? Let’s have a look:

The configuration above defines three stepped CI pipeline. The most interesting one is the integration test step, so let's have a bit closer look. For integration testing, we need some sort of data source and microservices that our account microservice talks to. The assumption here is that each microservice is dockerised and the docker images are held within GitLab docker registry. Within the .yml file we define that as a part of this step we want three other services running alongside – for that GitLab runner will pull latest images and start them up. After all that we can pass those to the integration-test goal as an environment variable. Those stages will be run for any code commit as we don’t specify a branch on which given step should be run. Below is a graphical representation of how will it look like on GitLab console:

As a next step, this CI pipeline could generate code quality report and push it to third-party provider tools (such as SonarQube).

Let’s assume that the business has DEV, QA and PROD environment. For each deployment we want it to be manually triggered by the developer/DevOps. In such case our pipeline would consist of four steps:

build docker image and push it to the repository with appropriate tag on it

For given CD pipeline only the build-image-and-push is an automatic step and will be trigger only when integration-test step passes. The deploy steps are manual and branch-specific. We won’t go into the details how does the deploy-* scripts look like as they will be different per infrastructure type.

When working with microservices it is crucial to have CI pipelines that could tell us if the whole system is consistent across all the microservices that builds it.

For that, we should have a separate project that would consist of a set of end to end tests and its own CI pipeline that would get triggered when a push to any of the microservices projects that build the solutions happens. Such CI pipeline can be set up on Gitlab Ci or Jenkins or any other standalone tool such as 

CI/CD pipelines

Achieve business goals and gain the edge by migrating your architecture.

Paweł Majkutewicz

A long time ago in a galaxy far, far away there was application. A pretty standard one, some UI with a 

 database. After a while a few problems arose:

once a while app crashes, so someone must restart it

the same situation with backups, they are handled by a custom script

So decisions were made - the app needs to be updated:

all crashes must be handled without user interaction

Therefore in the next chapters, we will migrate existing data to new MongoDB cluster and we will handle AWS application "upgrade".

Migrating MongoDB instance to the cluster

Having one instance of MongoDB available for the app is fine (😉). It is cheap and fast to create and deploy. Manage it also doesn't require too much effort. But it comes with few drawbacks - when something goes wrong and your instance goes down you have to bring it back online. This forces you to think about backups/snapshots, configurations, connections and so one. And this is a thing that no one wants to do it.

Instead of that, we can have a cluster, that will have redundancy, replication, automatic snapshots, so a lot of tasks will be done automatically.

Dump data from the current instance of MongoDB

The first step is to fetch all existing data from the running instance. This will be done using 'mongodump' utility. Unfortunately, I didn't have MongoDB installed on my machine, so it was obvious for me to use docker instance - I'll be able to switch mongo version in no time.

After a quick research, I've come up with bash script for making a dump for me. Most of it is boilerplate code for error handling, but the main part goes like this:

$MONG_VER - mongo version, so we can easily switch between 3.6 and 4.x

$SRC_HOST:$SRC_PORT - points to running MongoDB instance

-v $(pwd):/workdir - this mounts current dir as /workdir in docker instance

--archive=/workdir/dump/dump.gz - tells 'mongodump' to create archive file in /workdir/dump/ so effectively file will be created in ./dump/ directory

 - guessing that those guys should have the best knowledge and experience with mongo databases. Having own cluster is not complicated, go to their site, register and create a new project. And in project dashboard hit Build a New Cluster button. Next select Cloud Provider & Region and Cluster tier.

The most important thing here is to choose the appropriate cluster tier for our needs. In this case, M2 would be fine, but it has one drawback - it does not support peering (described later on):

And that is why we went with M10 cluster. In terms of backup, Cloud Provider Snapshots are enough, in that case, so we choose it. Last options are Cluster name, and naming thing is the hardest thing so after a couple of hours (😉) I was able to hit Create Cluster and after a while cluster is up and ready.

To be able to restore/import data our data we have to allow access to DB. First, we have to create a user that we will use and we can do it using Security -> Database Access menu. We have there ADD NEW USER button. After clicking it we have to fill a new user form:

Also, we have to whitelist our IP (or IP from which restore will be done). We can do it using ADD IP ADDRESS button in Security -> Network Access. If restore is performed from our machine, then we can use ADD CURRENT IP ADDRESS button.

It is time to import dumped data to the newly created cluster. Same situation here got bash script with a lot of error handling. The most important line is:

$MONG_VER - mongo version, so we can easily to switch between 3.6 and 4.x,

-v $(pwd):/workdir - this mounts current dir as /workdir in docker instance,

--archive=/workdir/dump/dump.gz - our dump,

$DEST_USER, $DEST_PASS - user credentials created in mongo cluster,

$DEST_HOST - points to running mongo instance,

$SRC_DB_NAME and $DEST_DB - allow us to rename our database, eg. original name was my-app-prod and we want to have dev instance named my-app-dev.

$DEST_HOST domain name of the created cluster. You can get this after clicking CONNECT on cluster dashboard:

And copy host part from connection string:

And that is all folks. We have running mongo cluster with our database. Now it is time to migrate the application.

Migrating AWS app to high availability architecture

In this part, we will take care of our running app. And now instead of using UI to create/deploy we will write CloudFormation script. This will give us the possibility to quickly redeploy the app.

Let's start from the smallest parts and go up in the hierarchy.

Our application is containerized in docker, so our basic block is TaskDefinition. We define here which docker image to use and some container configuration. All parameters required by the app are exposed as Parameters.

Next, we wrap the app instance with service. Service that runs and maintains the requested number of tasks and associated load balancers. All traffic that goes to app goes through service listeners, so let's check them now, cause as you can see we have a dependency on two of it.

Basically listeners handle all incoming traffic, we have two listeners.

The first listener redirects all HTTP traffic to HTTPS port.

HTTPS traffic are redirected to application (target group).

Specifies a target group for an Application Load Balancer or Network Load Balancer. Also it does health checks of our app. This solves our problem, when app die then will be automagically restarted.

AWS::ElasticLoadBalancingV2::LoadBalancer

And now lets define out load balancer. Basically we are allowing traffic from ouw group and from chosen one in ParAllowedSecurityGroup parameter - this is UI security group.

AWS::AutoScaling::AutoScalingGroup and AWS::AutoScaling::LaunchConfiguration

This part allows us to control how much instances of our app are running. For now, we just need one instance, but when appropriate time and our app will have over 2000 million users like facebook have than we can just increase our instances count and handle traffic flawlessly (😉).

Of course we have few more minor things. For example, after deploying our application we are updating api domain therefore UI is instantaneously redirected to newly created cluster.

AWS::EC2::SecurityGroup and AWS::EC2::SecurityGroupIngress

We have also security groups configured. Group is only allowing traffic from own security group - to manage load balancing.

Migrating AWS app with MongoDB to HA architecture. Visit our blog to learn more!

Hexagonal Architecture.

29 MARCH 2019 • 8 MIN READ