Setting up a Docker Swarm runtime environment

You can use Docker containers to run your APIs and applications being managed by API Connect. NOTE: This article refers to third-party software that IBM does not control. As such, the software may change and this information may become outdated. For the latest information, refer to https://www.docker.com/.

Before you begin

Before setting up a Docker Swarm, you need to determine its topology. A topology includes information about how many manager nodes and how many worker nodes the developer will have in the Swarm cluster. A topology also needs to determine the number of Docker registries and how these nodes are wired up with a virtual network. A cluster may be divided by multiple overlay networks. Each overlay network is isolated from other networks by default.

Note: The procedures in this article are for Docker version 1.13 and Docker Machine version 0.9.0. They may not work with other versions.

About this task

Docker automates the deployment of applications inside software containers. Docker containers wrap up a piece of software in a complete filesystem that contains everything it needs to run. Docker Swarm mode provides native clustering capabilities to turn a group of Docker engines into a single, virtual Docker Engine. For more information, see https://www.docker.com. You can use Docker containers to run your APIs and applications being managed by API Connect.

Docker Swarm provides high availability for worker nodes as well as manager nodes. Swarm dispatches the containers among all nodes registered to a Swarm cluster with a fair algorithm. However, the number of containers usually depends on the traffic and the system’s degree of high availability.

Docker Swarm provides high availability for manager nodes using a Raft algorithm, which needs an odd number of nodes registered as manager (3, 5, 7 and so on). This algorithm selects a leader among different manager nodes. Having three managers in the cluster provides a fault tolerance of one node, and having five nodes provides a tolerance of up to two nodes.

See https://github.com/ibm-apiconnect/docker-swarm-setup for the scripts used in this article

Setting up Docker Swarm

Procedure

Install the Docker machine on all of the nodes (both manager and worker nodes).
1. Update the application manager list.
  On Ubuntu, enter this command:
```
$ sudo apt-get update
```
  On Red Hat/Centos, enter this command
```
$ sudo yum update
```
2. Install and run docker-engine by entering the following command:
```
$ sudo curl -sSL https://get.docker.com/ | sh
```
Determine if the Docker daemon is running by entering this command:
```
$ sudo docker info
```
If the Docker daemon is not running, enter the following command to configure and start the Docker engine to listen for Swarm nodes on port 2377:
```
$ sudo docker daemon -H tcp://0.0.0.0:2377 -H unix:///var/run/docker.sock
```
Initialize the Swarm cluster on the first manager Docker host and make this machine a manager, by entering the following command:
```
$ sudo docker swarm init --advertise-addr <IP-address-of-manager>
```
Note: The initialize command returns different tokens for joining as a manager or a worker node.
Now repeat steps 1 and 2 on all of the nodes, and then join them to the Swarm using the following commands.
1. Add a worker to the Swarm by entering the following command:
```
$ sudo docker swarm join-token worker
```
  This command returns the command to execute on a worker host; for example, on Ubuntu (the command may be different on other systems):
```
$ sudo docker swarm join \
--token SWMTKN-1-343oklx5y9zqwc129p4ttvgxeeexh49vp
gslavcnqzipjmp2n4-0375hm0z4nto02l8jbt08ga1n \
Manager-IP-address:2377
```
  Where Manager-IP-address is the IP address of the Docker Swarm manager node.
2. Add a manager to this Swarm, by entering the following command:
```
$ sudo docker swarm join-token manager
```
  This command returns the command to execute on a manager host; for example:
```
sudo docker swarm join \
--token SWMTKN-1-343oklx5y9zqwc129p4ttvgxeeexh49
vpgslavcnqzipjmp2n4-bnfuijeolp487mllvj7l9sjil \
Manager-IP-address:2377
```
  Where Manager-IP-address is the IP address of the Docker Swarm manager node.
Create an overlay network on the first manager by entering the following command:
```
$ sudo docker network create -d overlay mynet
```
Your Swarm is now ready to use. Now it is time to create an image and push it to the Docker registry.

Setting up the registry using self-signed certificates

About this task

The server that hosts your registry should be separate from the manager or worker node servers.

Procedure

Create a directory on the registry host:
```
$ mkdir -p /etc/docker/certs.d/registry-host-FQDN:5000/
```
Where registry-host-FQDN is the fully-qualified domain name of the registry host.
Make the directory you just created current working directory:
```
$ cd /etc/docker/certs.d/registry-host-FQDN:5000/
```
Where registry-host-FQDN is the fully-qualified domain name of the registry host.
Generate the certificate and key in the certs folder:
```
$ openssl req -newkey rsa:4096 -nodes -sha256 -keyout domain.key -x509 -days 365 -out domain.crt
```
Note: Make sure you use a fully-qualified domain name as common name (CN) when generating the certificate and key.

Start the Docker registry container on the server that will host your registry by entering this command:

$ sudo docker run -d -p 5000:5000 \
--restart=always --name registry \ 
-v /etc/docker/certs.d/registry-host-FQDN:5000/:/certs \
-e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \ 
-e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \ 
registry:2

Where registry-host-FQDN is the fully-qualified domain name of the registry host.

Instruct all Docker Swarm hosts to trust the certificate by copying the domain.crtfile to the following location on all manager and worker hosts: /etc/docker/certs.d/registry-host-FQDN:5000/ca.crt, where registry-host-FQDN is the fully-qualified domain name of the registry host.

Building a Docker image for a LoopBack project

About this task

Once your microservice is ready, follow steps one through five below to package your API using npm and create a deployable image to run in a Docker Swarm runtime environment.

Note: You must perform these steps on the local machine where you develop LoopBack applications. It needs to have Docker Host and Docker Machine installed and connectivity to your Docker Registry.

Then follow steps six and seven to tag and push your image to an internal Docker registry. You can replace the last two steps with publishing your image to another public or private Docker registry such as Docker hub.

Procedure

Go into the directory containing your LoopBack app, for example, assuming it's called “microservice”:
```
$ cd microservice
```
Package your LoopBack app:
```
$ npm pack microservice
```
This command creates a tar file called microservice-1.0.0.tgz.
Copy the microservice-1.0.0.tgz to the microservice directory.
```
$ cp microservice-1.0.0.tgz microservice
```
Note: The number at the end of the file name is based on the version property in the application's package.json file. Depending on the version of your application, you may see a different number.

Create a file named Dockerfile and add the following text to it:

FROM node:argon
RUN mkdir -p /usr/src/app
WORKDIR /usr/src/app/package
ADD microservice1-1.0.0.tgz /usr/src/app/
RUN npm install
EXPOSE 3000
ENV NODE_ENV production
CMD [ "npm", "start" ]

Build your image by entering the following command:
```
$ docker build -t microservice1 .
```
Tag your image by entering the following command:
```
$ docker tag microservice1 registry-host-FQDN:5000/ microservice1
```
Where registry-host-FQDN is the fully-qualified domain name of the registry host.
Push the image to the registry by entering the following command:
```
$ docker push registry-host-FQDN:5000/microservice1
```

Building a Docker image for a Java application

About this task

The following instructions show how to create a Docker image for your Java API if you already have a JAR package. Alternatively, you could use a Maven plug-in to create and publish your image to a Docker registry.

Procedure

Go into the root directory of your Java application (the directory that contains the pom.xml file), for example, assuming it's called “microservice”:
```
$ cd microservice
```
Package your Java application:
```
mvn package
```
This creates a microservice-1.0.0.jar file in the target subdirectory by default.
Copy microservice1-1.0.0.jar to the microservice directory.
Note: The numeric suffix in the JAR file name is determined by the version specified in the application pom.xml file. This example assumes that it is "1.0.0".
```
$ cp microservice1-1.0.0.jar microservice
```

Create Dockerfile and add the following text to it:

FROM frolvlad/alpine-oraclejdk8:slim
RUN mkdir -p /usr/src/app
WORKDIR /usr/src/app/
ADD microservice1-1.0.0.jar /usr/src/app/
EXPOSE 8080
ENV ENV production
ENTRYPOINT ["java","-Djava.security.egd=file:/
dev/./urandom","-jar","/usr/src/app/microservice1-0.0.0.jar"]

Follow the steps five to seven in the previous section to build your image and push it to the image registry.

Adding Docker Swarm visualizer tool

About this task

Docker Swarm provides a visualization tool to show the topology of the cluster as well as information about containers. The visualization tool runs as an extra container that you can start as a new service in Docker Swarm.

Procedure

Start the service for the visualization tool by entering the following command in the first manager:

docker service create \
--name=viz \
--publish=8080:8080/tcp \
--constraint=node.role==manager \
--mount=type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock \manomarks/visualizer

Adding a health check for LoopBack application

About this task

Docker Swarm provides a mechanism for a health check of each container. If a container is terminated after a health check, Swarm starts a new container to replace the terminated one. Since a microservice runs in an isolated process, and Docker Swarm does not communicate with the process running inside a container, you can implement service health check by adding an additional endpoint in the API without exposing it to the API consumers in the Swagger file.

You can implement this endpoint in a LoopBack app by adding a new component as detailed below. Note that this REST endpoint is available only to the cluster. No API consumer can hit this endpoint since it is not listed in the Swagger file and the API is protected by DataPower.

Procedure

In your LoopBack project, edit server/component-config.json and add the following:
```
{
...
  "node-docker-health": { }
...
}
```
Install the node-docker-health package:
```
npm install --save node-docker-health
```
This command installs the package and updates the application dependencies.

Edit the Dockerfile and add the following line before building an image:

HEALTHCHECK CMD curl --fail http://localhost:<APIPORT>/<RestApiRoot>/vitals/node-docker-health || exit 1