DEV Community: Brian Hannaway

Running Multiple Spring Boot Services with Docker Compose

Brian Hannaway — Tue, 25 Aug 2020 22:18:46 +0000

In this post we’ll look at how Docker Compose makes it easier to configure and run multiple containers in your local environment.

Why Docker Compose?

First up, you don’t need Docker compose to run multiple containers. You can do this just fine by manually starting and stopping the containers yourself, as shown previously in this post. However, as the number of containers in your application grows, it becomes more cumbersome to manage each container manually.

Docker compose simplifies things by allowing you to configure a multi container application in a single YAML file. You can start and stop all containers in the application with a single command.

Sample App Code

I’ve created a sample app for this post which you can pull from Github. It contains the following

2 Spring Boot applications
- Bank Account Service – exposes a REST API for creating and reading bank simple account details
- Config Service – exposes a REST API with application configuration for the Bank Account Service
2 Dockerfiles – to define the container images for the above services
A Docker compose file defining the multi container application

Aside form the Docker side of things, I wont go into any detail on the Boot services. If you want more info you can check out this previous post.

Bank Account Service Dockerfile

We’ll begin defining a Docker image for the Bank Account Service.

# MAINTAINER Brian HannawayFROM openjdk:8-jre-alpine
WORKDIR /app
# Add wait script to the image - script pulled from https://github.com/ufoscout/docker-compose-wait/releases/download/2.7.3/wait /wait
COPY /scripts/wait /app/RUN chmod +x /app
RUN apk --no-cache add curl
COPY /target/bank-account-service-0.0.1-SNAPSHOT.jar /app/
CMD ./wait && java -jar bank-account-service-0.0.1-SNAPSHOT.jar

FROM openjdk:8-jre-alpine tells Docker to use the openjdk:8-jre-alpine base image.

WORKDIR /app tells Docker to create a new working directory in the image called /app. All further commands will run from this directory.

COPY /scripts/wait /app/ tells Docker to copy the wait script from the scripts directory on the host to the /app directory in the image. I’ll explain the purpose of the wait script in detail later.

RUN chmod +x /app makes the contents of the /app directory executable

COPY /target/bank-account-service-0.0.1-SNAPSHOT.jar /app/ copies the service JAR from the target directory on the host to the /app directory in the image

CMD ./wait && java -jar bank-account-service-0.0.1-SNAPSHOT.jar runs the wait script, followed by the bank account service. The service won’t run until the wait script has finished.

Config Service Dockerfile

Next we’ll define the Config Service Docker image. Its a slightly simpler version of the image we created for the Bank Account Service above. We’ll simply create a working directory, copy in the service JAR and run it.

FROM openjdk:8-jre-alpine
MAINTAINER Brian Hannaway
WORKDIR /app
COPY /target/config-server-0.0.1-SNAPSHOT.jar /app/
ENTRYPOINT ["java", "-jar", "config-server-0.0.1-SNAPSHOT.jar"]

Defining the Docker Compose File

Now that we’ve defined Dockerfiles for the Bank Account and Config services, the next step to create a docker-compose file that describes how we’ll uses these images to run containers.

version: "3"

services: 
   config-service: 
      image: config-service 
      container_name: config-service 
      networks: 
         - micro-service-network 
      ports: 
         - 8888:8888 

   bank-service: 
      image: bank-service 
      container_name: bank-service 
      networks: 
         - micro-service-network 
      ports: 
         - 8080:8080 
      environment: 
         WAIT_HOSTS: config-service:8888

networks: micro-service-network:

version: "3" tells Docker that we’re using version 3 of the docker-compose file format. At the time of writing version 3 is the latest and recommended version. The docker-compose format version you use will be dictated by the version of Docker you’re running. I’m running Docker version 19.03.12 which means that I should be using version 3. If you want to check what version of docker-compose is compatible with your Docker version, check out this compatibility matrix.

Services Definition

The services section defines the containers that make up your application. Each service definition contains all the configuration required to start a container from an image. The information in each service definition is what you’d typically supply on the command line, running a container manually.

config-service: 
   image: config-service 
   container_name: config-service 
   networks: 
      - micro-service-network 
   expose: - "8888"

Config Service

The config-service section defines all the configuration docker needs to run the config-service container

image tells compose which image to use to run the container.

container_name is the name given to the container when it starts. If we don’t specify a name, compose will derive one based on the name of the compose file and the image name. For example, if I omit the name attribute for the config-service and run docker-compose up , I can see that the containers derived name is boot-microservices-docker-compose_config-service_1.

Generally its a good idea to give your containers a meaningful name. You’ll see later that we need to reference config-service from the bank-service. We’ll do this using the name specified in container_name.

networks defines the networks that the config-service container will join when it starts. In this instance it will join micro-service-network, which we’ll define later.

expose lists the ports that are exposed on the container. The ports are exposed on either the default network or any network the container is attached to. The ports are not exposed to the host machine. To do this you’ll need to use the ports attribute and supply the appropriate mappings.

Bank Service

The bank-service definition is very similar to what we’ve already defined, with the image, container_name, networks and expose attributes being similar to those defined for the config-service

bank-service:
   image: bank-service 
   container_name: bank-service 
   networks: 
      - micro-service-network 
   expose: - "8080" 
   environment: 
      WAIT_HOSTS: config-service:8888

The environment attribute is used to specify a list of environment variables for the container. In the bank-service we specify the environment variable WAIT_HOSTS and give it the value config-service:8888. In short, this is required to control container start up order and ensure that the config-service is up and running before the bank-service starts. I’ll explain this in detail later.

Networks Definition

The networks section allows you define a network for your services. For our application we defined a network called micro-service-network. When you run docker-compose up, each container that starts will be added to the micro-services-network and will be visible to every other container in the application. Containers can reference one another via their host name, which is the same as the service name. So in our sample application, the banks-service is able to access the config-service as config-service:8888.

If we don’t explicitly define a network, Docker will create one by default and add all services in the compose file to it.

Running the Application

Running the docker-compose up command will

create a bridge network called micro-service-network
start a container using the config-service image. The container will expose port 8888 on micro-service-network and will be accessible to other containers via host name config-service.
start a container using the bank-service image. The container will expose port 8080 on micro-service-network and will be accessible to other containers via host name bank-service.

It takes approximately 20 seconds for both the bank-service and config-service to start. If you run docker container ls you should see the two containers that have just been created.

Service Dependencies & Startup Order

Its common to have dependencies between containers, such that a container A requires container B to be running before container A can start. Compose allows you to handle this scenario to a certain degree, by defining the startup order using the depends_on attribute. For example, the compose file below defines a web service and a db service, where web is dependent on db.

version: '3'

services: 
   web: 
      image: myWebApp 
      depends_on: 
         - db 
      db: 
         image: postgres

In the above example, compose will start the containers in dependency order, so db will be started before web. Although depends_on sets the order in which containers are started, it does not guarantee that Postgres, inside the db container is fully operational before the web container starts.

We have a similar problem in our sample application because bank-service tries to call config-service on startup. If config-service isn’t fully stood up and available to take requests on port 8888, bank-service will fail. Using the depends_on attribute to start the config-service first, won’t guarantee that the config-service is fully operational before bank-service calls it.

Introducing docker-compose-wait

docker-compose-wait is a great command line utility that solves the problem described above. When defining the bank-service earlier we made docker-compose-wait available to the image by copying the wait script into the app directory.

# Add wait script to the image - script pulled from https://github.com/ufoscout/docker-compose-wait/releases/download/2.7.3/wait /waitCOPY /scripts/wait /app/

We then told Docker to run the wait script along with the JAR when starting the container.

CMD ./wait && java -jar bank-account-service-0.0.1-SNAPSHOT.jar

When we defined bank-service in the docker-compose file, we included a WAIT_HOSTS environment variable that referenced config-service on port 8888. When we run docker-compose up, the wait script pings config-service on port 8888. It will not allow bank-service container to start until config-service is up and running on port 8888.

We can see this in action in the log snippets below. The wait script checks if config-service is available on port 8888, initially reporting that it isn’t available.

Eventually config-service bootstraps and is up and running on port 8888. The wait script then reports Host config-service:8888 is now available and the bank-service container is started.

Wrapping Up

In this post we looked at how docker-compose makes it easy to manage multiple containers in a simple single node environment. This is particularly useful for development environments and automated test environments. If you want to manage multiple containers in a multi node environment, then Docker Swarm is a better bet. We’ll look at Swarm in another post soon.

The post Running Multiple Spring Boot Services with Docker Compose appeared first on briansdevblog.

Be Nice – Comment your Code

Brian Hannaway — Fri, 30 Aug 2019 10:47:05 +0000

I’ve always been a fan of commenting code. To me, it’s a no brainer, the sensible thing to do, and a fundamental part of building software that’s easy to understand and maintain. Not everyone agrees though. Some argue that comments are unnecessary and simply shine a light on code that isn’t as expressive as it should be. In this post I’ll try to counter those arguments and tell you why I think quality comments are an important part of building software that easier to understand and maintain.

Helping Others Understand Your Code

As developers, we spend a considerable amount of time reading and trying to understand other peoples code. At times this can be a difficult and frustrating task. Most of us have been in a situation where we’re neck-deep in legacy code with no documentation, no unit tests and not a comment in sight. Chances are the guy who wrote it isn’t around anymore and we’re left to our own devices to figure out WTF is going on. Not much fun, is it?

These experiences should remind us that as developers we have a responsibility to go beyond implementing functional requirements and write code that’s easy to read, understand and maintain. A code base that’s easy to understand, makes life easier for your future self and those coming behind you. It allows developers with varying levels of technical ability and domain knowledge to jump into your code and become productive with the least amount of pain.

Comments – Just One Piece of the Puzzle

When it comes to crafting code that’s easy to understand and maintain there are a number of important pieces in the puzzle. Based on my own experience I’d order these as follows.

good structure – classes with a single responsibility, functions that do one thing
descriptive naming – classes, functions and variables should have clear, descriptive names
unit test coverage – unit tests describe how a component should behave. As well as testing expected behaviour they act as a form of component specification
comments – comments provide important information that can’t easily be expressed by the code.

You might be surprised that comments are at the bottom of the list. That’s not to play down the importance of comments, but rather to highlight the importance of the other factors. Emphasis should always be placed on writing well structured, expressive code that’s easy to understand. Think of comments as the icing on the cake, that exist to provide the reader with information that can’t easily be expressed by the code itself.

Think about Your Audience

Over the lifetime of a system, developers with varying levels of technical ability, experience and domain knowledge will work on the code. At one end of the spectrum, you may have very experienced tech lead/architect level guys, while at the other end you may have graduate developers fresh out of college. The point is, you don’t know exactly who’ll be working on your code in the future or what level of expertise they’ll have. With this in mind, you should make your comments accessible and useful to as broad a range of readers as possible. If you’re an experienced tech lead with strong domain knowledge, you shouldn’t comment your code assuming that the guy coming behind you will know as much as you do. Instead, write your comments with less experienced developers in mind.

You could argue that this runs the risk of comments that are too obvious, especially for more experienced developers. While this is a risk it’s important to remember that when we describe a comment as obvious we’re being subjective. Something that’s obvious to a tech lead with 15 years experience may be anything but obvious to a junior developer.

What and Why

There are essentially 2 things you’ll want other developers to grasp when they’re looking at your code. What the code is doing and why it’s doing it. Let’s take a closer look.

Comments that explain What

Well written code in many cases will be self-documenting. Your aim should be to make your code as expressive as possible, therefore reducing the need for comments that describe what the code does. However, there are times when describing what the code does is useful.

When the business logic is complex you should use comments to describe your intent. Yes, you still want to make the code as self-descriptive as possible but comments add value in this instance by describing what you’re trying to achieve. As we all know, what the code does and what it’s meant to do is not always the same thing
Some code simply isn’t expressive. Take regular expressions as an example. Yes, you can give a regex a descriptive name but it might not help the reader understand the pattern that’s being resolved. In this instance, comments that describe the pattern and provide sample matches are really useful. Complex SQL is another example of code that doesn’t tend to be very expressive. Some simple comments can help guide the reader by describing the intent of the statement.
Domain concepts can be difficult to describe. It sounds straight forward, but naming things well can be very tricky, especially in a complex domain. I’ve spent quite a bit of time working in life assurance and pensions. I sometimes find it difficult to encapsulate the purpose of a class, function or variable in a simple name. In these situations, I’ll come up with the most descriptive name possible and then add a comment to describe in plain English, what the class, method or variable represents in business terms.

Comments that explain Why

Comments that explain why your code does something are very important because this information can’t be derived from the code. Below are a few examples of when it’s important to explain why you’ve chosen to do something.

Design Decisions – Comments that explain why you’ve made design decisions are important, especially if you’ve implemented some kind of pattern that you expect other developers to leverage in the future. A guiding hand can help point people in the right direction by showing them the most appropriate way to extend existing functionality. Making it clear why you’ve done something also reduces the chances of someone refactoring your code in the future and inadvertently breaking a pattern you’ve put in place.
Workarounds – we sometimes have to work around problems caused by external factors we have little or no control over. Perhaps data received from an external system needs to be tweaked in certain instances before it can be processed. Workarounds like this, while not ideal are a reality of enterprise development, especially where legacy systems are involved. Comments help by explaining the root of the problem and why we need to work around it. Comments provide other developers with context and reduce the chances of someone removing the workaround because they don’t understand it.
Edge cases – We sometimes write logic that has to handle peculiar edge cases. These scenarios aren’t usually intuitive and are therefore an excellent candidate for comments. Logic that handles quirky scenarios often seems more complicated than it needs to be. Comments are a good way to explain the edge cases and why you’ve implemented the solution you have.

Conversational Comments

I try to keep my comments informal and conversational. Imagine one of your teammates is sat beside you and you’re explaining how some part of your code works. You’d explain in simple terms, making it as easy as possible for your teammate to understand. I think comments should read the same way by using simple language to get the point across. Remember, comments are there to provide information that the code can’t, so make them as easy to digest as you can.

Quality Over Quantity

Like most things in life, there should be an emphasis on quality over quantity. Comments should be used thoughtfully, to tell the reader something that can’t be easily expressed by the code. Well structured, expressive code with a sprinkling of useful comments is much better than poorly written code with a ton of comments explaining what each and every line does.

Avoid superfluous comments that echo something clearly described by the code. Comments, like code, evolve over time and need to be maintained. Avoiding superfluous comments reduces the maintenance overhead and helps the reader focus on the comments that are important.

Avoid Comment Rot

Comment rot is when the code is updated but the accompanying comments are not. This leads to comments that are out of date and often contradictory to the code they’re supposed to describe. Comment rot is often cited as a major downside to commenting code but I think this argument is weak. While I agree that comment rot is a bad thing and something to be avoided, it’s not a good enough reason to stop commenting your code. The best way to avoid comment rot is obvious…..update comments when you update the code. Like most good practice this requires a combination of developer discipline and governance in the form of code reviews.

Wrapping Up

Comments aren’t a substitute for well structured, expressive code but they can help by providing information that isn’t easily expressed by the code itself. Code that’s easier to read, understand and maintain, ultimately translates to greater productivity with more features being shipped, and I’ll bet that’s what keeps your boss happy.

The post Be Nice – Comment your Code appeared first on briansdevblog.