3.8 Using Docker

The Docker open platform has excellent documentation which you should read and understand.

3.8.1 Why Docker?

Docker is a container-based platform that enables you to develop, deploy, and run applications within a container. Your application, plus any dependencies your application requires, such as binaries and libraries, and configuration information are held within the container. You can deploy multiple containers, all of which run in Docker and on top of the operating system.

Using Docker you can scale your applications vertically, meaning multiple instances of the session server can exist on one server and each instance will perform exactly as it did when you created and tested it.

3.8.2 What are the benefits?

Containerization delivers multiple benefits:

  • Performance

    Virtual machines are an alternative to containers, however containers do not contain an operating system (unlike VMs). This means containers are faster to create, quicker to start, and have a much smaller footprint.

  • Agility

    Because containers are more portable and have better performance, you can take advantage of more agile and responsive development practices.

  • Isolation

    Docker containers are independent of one another. This is important because a Docker container containing one application, including the required versions of any supporting software, will not interfere with another container of the same application which requires different supporting software. You can have total confidence that at each stage of development and deployment the image you create will perform exactly as expected.

  • Scalability

    Creating new containers is simple and quick. The Docker documentation has information on how to manage multiple containers.

3.8.3 Terminology

There are basic terms you need to be familiar with when working with Docker. For more information see the Docker Documentation site.

  • Container
  • A run-time instance of an image. A container is usually completely isolated from the host environment, only able to access host files and ports if it has been configured to do so. To run an image in a container you use the docker run command.
  • Docker Hub
  • A cloud-based community resource for working with Docker. Docker Hub is typically used for hosting images, but can be used for user authentication and automating the building of images. Anyone can publish images to Docker Hub.
  • Docker Compose
  • Compose is a tool that uses YAML files to configure your application services and then define and run multi-container Docker applications. To learn more about Compose visit the Docker Compose documentation.
  • Dockerfile
  • A text document containing the commands to build a Docker image. You can specify complex commands (such as specifying an existing image to use as a base) or simple ones (such as copying files from one directory to another). To build an image from a Dockerfile you use the docker build command.
  • Image
  • A standalone, executable package that runs in a container. A Docker image is a binary that includes everything needed to run a single Docker container, including its metadata. You can build your own images (using a Dockerfile) or use images that have been built by others and then made available in a registry (such as Docker Hub). To build an image from a Dockerfile you use the docker build command. To run an image in a container you use the docker run command.

3.8.4 Getting Started with Docker and Host Access for the Cloud

When you install HACloud, if you choose to use Docker, the install package contains an initial Dockerfile and accompanying application jar file to get you started using the session server in containers. These files are available prior to your installation.

NOTE:Make sure you are running the latest version of Docker and Docker Compose.

There are examples located in the docker/samples folder. See Examples for instructions.

There are four steps involved in creating the base image:

  1. Install Docker. Follow the instructions on the Docker web site.

  2. Extract the download package file and locate Dockerfile,entrypoint.sh and sessionserver.jar in the Docker folder. The entrypoint.sh file must have the executable bit set.

  3. Build the Docker image.

  4. Run the Docker image.

Build the session server Docker image

Assuming you have followed steps one and two; installed Docker and extracted and located Dockerfile and sessionserver.jar, the next step is to build the base Docker image of the session server.

  1. Run this command from the folder containing the Dockerfile:

    docker build -t hacloud/sessionserver:<version> .

    Replace <version> with the version of the session server. If a version is not available, the default tag (-t) is latest.

  2. Verify that the image was successfully created. Run:

    docker images

    The output should contain information about the image you just built.

Run the image

Before you can run the session server image in a Docker container, you must complete the following steps:

Specify the address of the MSS server

To specify the location of your MSS server, pass in an environment variable to the session server through Docker. For example, --env MSS_SERVER=mss.server.com

Specify the service registry password

To specify the service registry password, pass in an environment variable to the session server through Docker. For example, --env SERVICE_REGISTRY_PASSWORD=<your_password>.

You can retrieve the password from the service.registry.password property located in ./mss/server/conf/container.properties on the MSS server. Use the entire service.registry.password property.

Tell MSS to trust the session server’s identity certificate

You accomplish this step using the Administrative Console > Configure Settings > Trusted Certificates. See the MSS Administrative Console documentation, Trusted Certificates. The session server’s certificate is available in the sessionserver/etc directory.

Provide the keystore containing the session server’s identity certificate

The session server identifies itself using a certificate. The certificate is expected to be present in the Java keystore /sessionserver/etc/keystore.bcfks located in the container.

Provide the truststore containing the MSS certificate

When the session server makes outbound TLS connections, it verifies the trust of the remote servers (such as MSS) using certificates in its truststore. The certificates present in the Java keystore /sessionserver/etc/trustcerts.bcfks located in the container will be trusted.

Mapping your keystore and truststore to the ones in the container

You have two options to provide these keystores into the container:

Using a volume mount

A volume mount mounts a file or directory on the host machine into a container. The file or directory is referenced by its full or relative path on the host machine.

This volume mounts the keystore and truststore files on the host to the Docker container.

docker run --env MSS_SERVER=localhost \
--env SERVICE_REGISTRY_PASSWORD=<enter password here> \
--volume ~/demo_keystore.bcfks:/sessionserver/etc/keystore.bcfks \
--volume ~/demo_truststore.bcfks:/sessionserver/etc/trustcerts.bcfks \
--publish 7443:7443 \
sessionserver

There is a downside to using a volume mount. Since keystore stores must be located on each Docker host where a container is running, your Docker container will not be very portable.

Extending an existing Docker image

With this method you create a new Dockerfile to copy the files you need into the Docker image. This makes your Docker image more portable.

First, create a Dockerfile that will extend from the hacloud/sessionserver Docker image.

FROM hacloud/sessionserver:<for example, hacloud/sessionserver:latest or hacloud/sessionserver:version>

COPY <your-path>/keystore.bcfks /sessionserver/etc/keystore.bcfks
COPY <your-path>/truststore.bcfks /sessionserver/etc/trustcerts.bcfks

Next, create the extended Docker image, naming it demo.

docker build -t demo .

Finally, run the demo image.

docker run --env MSS_SERVER=localhost \
--env SERVICE_REGISTRY_PASSWORD=<enter password here> \
--publish 7443:7443 \
demo

Specify Docker host name and port

The session server needs to broadcast its host name for MSS to find it. Because Docker generates a random unique name that isn’t reachable outside the container, you need to specify your Docker host’s name for MSS. It is also necessary to tell the session server which port you are publishing on your Docker host. Clients accessing the session server will end up hitting <docker_host_name>:<docker_published_port>.

--env HOST_NAME=docker_host_name
--env SERVER_PORT=docker_published_port

3.8.5 Examples

The examples, located in the docker/samples folder, walk you through four scenarios using Docker Compose. Compose is a tool that uses a YAML file to configure and run your applications with a single command.

Prerequisites

To run the examples:

The examples include:

  • Basic - A basic example providing a demo keystore and truststore files in which you can import a MSS server certificate.

  • Hybrid - An hybrid example which assumes a local Host Access for the Cloud installation and mounts existing, on disk, keystore and truststore files to the Docker container.

  • Extensions - An extension example showing how to update, modify, and customize the web client.

  • Load Balance - A load balancer example illustrating how to balance between linked containers.

Basic

This basic example illustrates how to run the session server Docker image in Docker Compose. For this example you will need to import your MSS server’s certificate into the provided sample./certs/demo_truststore.bcfks using something like KeyStore Explorer. Your MSS certificate, by default, is located at /mss/server/etc/<computer-name>.cer. See Import a certificate into the session server’s truststore.

Before running the example, update the MSS_SERVER, HOST_NAME, and SERVICE_REGISTRY_PASSWORD values in docker-compose.yml.

  • To start the session server service:

    docker-compose up

  • To run the service in a daemon (detached mode):

    docker-compose up -d

  • To look at running containers:

    docker ps

Hybrid

In this example a local installation of Host Access for the Cloud, with existing keystore and truststore files on disk is present. These files will be mounted (copied) to the Docker container.

Before running the example, update the MSS_SERVER, HOST_NAME, SERVER_PORT, and SERVICE_REGISTRY_PASSWORD values in the .env file.

To start the session server service:

  • Copy.env and docker-compose.yml to sessionserver/microservices/sessionserver/.

  • From this directory, run: docker-compose up -d

Extensions

Using extensions and your own HTML, CSS, or JavaScript, you can update, modify, and customize the presentation of the web client from within the browser. See Extending the Web Client for more information.

This example sets SPRING_PROFILES_ACTIVE to extensions-enabled and maps the location of the extensions in docker-compose.yml.

Before running the example, update the MSS_SERVER, HOST_NAME, and SERVICE_REGISTRY_PASSWORD values in the.env file.

To start the session server service:

docker-compose up -d

You could also choose to extend the base hacloud/sessionserver Docker image and copy the extension files into the Docker container:

  1. Create the Dockerfile that extends from the hacloud/sessionserver Docker image.

    FROM hacloud/sessionserver

COPY ./certs/keystore.bcfks /sessionserver/etc/keystore.bcfks
COPY ./certs/trustcerts.bcfks /sessionserver/etc/trustcerts.bcfks
COPY ./extensions /sessionserver/extensions/

  2. Create the extended Docker image and name it extensions.

    docker build -t extensions

  3. Update docker-compose.yml to use the new extensions image

    version: '3'
services:
  sessionserver:
    image: extensions
    environment:
      - LOGGING_FILE_NAME=./logs/sessionserver.log
      - LOGGING_FILE_MAXSIZE=10MB
      - LOGGING_FILE_MAXHISTORY=10
      - MSS_SERVER=${MSS_SERVER}
      - SERVICE_REGISTRY_PASSWORD=${SERVICE_REGISTRY_PASSWORD}
      - SPRING_PROFILES_ACTIVE=extensions-enabled
    ports:
      - ${SERVER_PORT}:7443

Load Balance

HAProxy is a load balancer. Learn more about HAProxy on their web site.

In this example, an haproxy service is included in the docker-compose.yml file. The example uses an haproxy image to balance between linked containers. This example uses SSL Bridging to link the containers.

To provide secure communication between the clients and the load balancer, you must update the LOAD_BALANCER_CERT property in the.env file with the location of the load balancer certificate.

To help you test, you can generate a self-signed certificate:

  1. Generate a unique private key (KEY):

    sudo openssl genrsa -out mydomain.key 2048

  2. Generate a Certificate Signing Request (CSR):

    sudo openssl req -new -key mydomain.key -out mydomain.csr

  3. Create a Self-Signed Certificate (CRT):

    sudo openssl x509 -req -days 365 -in mydomain.csr -signkey mydomain.key -out mydomain.crt

  4. Append KEY and CERT to loadbalancer.pem:

    sudo cat mydomain.key mydomain.crt >./certs/loadbalancer.pem

To start the session server and haproxy services: 

docker-compose up -d

-or-

docker-compose up --scale sessionserver=n -d

Where n is the number of session server instances.

You can change the number of session server instances after the services start:

docker-compose scale sessionserver=n

To access the session server and HAProxy stats page:

  • https://server:7443

  • http://server:1936/haproxy?stats

Using:

  • user: admin

  • password: password