Provisioning a Docker Compose workload

With Docker Compose workloads, users have the possibility to manage multiple services in the Nerve system and establish a link between them. Users can also use a Docker container in combination with a compose file to use the full extent of Docker Compose. In contrast, a Docker workload in the Nerve system is designed to cover basic functionalities and configuration options of a Docker container through the UI of the Management System.

Before provisioning a Docker Compose workload, a compose file needs to be written.

Docker Compose file

A Docker Compose file is required when provisioning the workload. It needs to be written in YAML format. For information on how to write a Docker Compose file, refer to the official Docker Compose documentation. However, keep the following things in mind:

• Nerve validates the compose file to v3.5 of the compose schema. Follow this schema to write a valid compose file.
• The image attribute is required to be included in the compose file. It also needs to be consistent with the image specified through the UI.

The validation check for the compose file schema happens as soon as the file is uploaded in the workload settings with the UI giving a message whether the check has passed.

When writing compose files, note the differences between public Docker Hub registries and private registries. Private registries require the full URL to be specified, as well as a username and password if they require authentication. Public Docker Hub registries can be specified in their short form. Visit Docker Hub to find Docker images and their paths.

Examples:

• Public Docker Hub registry

  nodered/node-red-docker
nginx

• Private registry with authentication and a tag at the end

  auth.docker.test.host.cloud/workload:v1.3

Restrictions and constraints

Certain options are not allowed due to security concerns. These options are validated in a second check during the deployment process of the workload. Take a look at the list of prohibited parameters:

- network_mode: "host"
or
 - networks:
     nerve-test:
         name: nerve-test
         driver: host

The host network cannot be used. Use the default bridge network or user-defined bridge networks. Predefined Nerve networks can also be used. Refer to Networks for Docker workloads for more information.

- ipam:...

It is not possible to use ipam parameters for configuring networks in order to specify a custom driver or a subnet, for example.

- privileged: true

Privileged mode cannot be set for any service. This is to avoid the container having root capabilities on the host.

- volumes:
      - type: bind
        source: ./static
        target: /opt/app/static
or
- /opt/data:/var/lib/mysql (where the first part is a host path)

Bind mounts to host locations are not allowed. The only exception is /etc/localtime. This allows a service to use the host time zone setting.

Environment variables

There is a set of restrictions and constraints for defining environment variables, especially when working with Nerve DNA. The Nerve system handles certain aspects in a certain way due to security concerns, which makes two things not possible:

1. Environment variables cannot be used for ports to avoid the possibility of workload ports being reserved more than once.
2. Environment variables cannot be used for volumes, bind volumes specifically, because users are restricted from using bind volumes with Nerve.

However, to work around the above restriction in regards to environment variables being used for ports, certain things should be considered:

1. It is recommended to define default values for environment variables in the Docker Compose file. Otherwise they cannot be set via the Management System but only through the Nerve DNA process in an ENV file.
2. Specific syntax should be used to make sure that environment variables from ENV files are considered as well.

Consider these suggestions especially when one Docker Compose workload is to be used on different nodes with ENV files further configuring environment variables for specific nodes.

Take a look at the following excerpt of a compose file as an illustration:

    restart: unless-stopped
    environment:
      - NGINX_PORT=${NGINX_PORT:-81}
    ports:
      - "8888:80"
      - "8889:81"

An environment variable NGINX_PORT is defined as NGINX_PORT=${NGINX_PORT:-81}, following this syntax rule:

• ${VARIABLE:-default} evaluates to default if VARIABLE is unset or empty in the environment.

So in the file above this means that the value for NGINX_PORT will be 81, unless NGINX_PORT is defined in an ENV file that has been added through the Nerve DNA process.

While there are corner cases and combinations of defining environment variables that work with Nerve as well, the way described above is the recommended best practice to avoid error cases and complications.

For more information on working with Nerve DNA, refer to Nerve DNA.

Provisioning a Docker Compose workload

The following instructions only cover the required settings for provisioning a Docker Compose workload. Optional settings will be left out. Extended options are addressed in the last section of this chapter. However, note that some settings are necessary to provision a functioning workload. Make sure to understand the workload and its purpose before provisioning a workload.

Other workload types that can be provisioned are:

• CODESYS workloads
• Virtual Machine workloads
• Docker workloads

The process for each workload is highlighted in its respective chapter.

1. Log in to the Management System.
2. Select Workloads in the navigation on the left.

3. Select the Docker Compose symbol (Add new Compose workload) in the upper-right.

   

4. In the new window, enter a name for the workload.

5. Select the plus symbol next to Create version to add a new version of the workload.

   

6. In the next window, enter the following information in the Basic tab:

   Category

   Settings and descriptions

   VERSION SPECIFIC INFO

   Version name Enter a name for the version of this workload. Compose file Select the upward arrow symbol to open the file browser and upload a compose file for the Docker container here. The compose file needs to be written according to the Docker Compose schema v3.5. Note that the image paths need to be included in the compose file for every container or service. Refer to Docker Compose file for more information. Once a compose file is added, its contents are displayed on the right. Note that the attributes of the compose file in the screenshot are example attributes.

   Note

   Once a compose file has been uploaded, the Registries and Services and Remote Connections tabs become active and can be used for configuration. Refer to Settings for Docker Compose workloads for information on the settings.

7. Select Save in the lower-left corner to save the workload version.

The workload has now been provisioned and is ready to be deployed in the Deploy menu. For more information on how to control the workload after deployment and use workload specific features, refer to Workload control.

Settings for Docker Compose workloads

In the instructions above, all optional settings have been left out. Below is an overview of all the options with an explanation to each option.

Basic tab

Registries and Services tab

Remote connections tab

Example compose file

This section presents an example compose file that can be used to provision a Compose workload immediately. It is designed for trying out Docker Compose workloads. The applications used for the examples are PostgreSQL and Grafana.

The PostgreSQL service is defined with the name db using the postgres container image. The container exposes the port 5432 that must be available for linked services. The file shows how to define environment variables and a named volume for the container. At deployment time, a default network is created and the container joins it under the name db.

The Grafana service shows how to map the container port to a host port. Most importantly, it shows how to connect the container to an existing Nerve network. The use of pre-configured Nerve networks for Docker and Docker Compose workloads is recommended. Refer to Node internal networking for more information on Nerve networks.

version: '3.5'
services:
   db:
    image: postgres:alpine
    environment:
      - POSTGRES_USER=admin
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=postgres
    restart: always
    volumes:
      - db_data:/var/lib/postgresql/data
    expose:
      - 5432
   grafana:
    image: grafana/grafana:7.5.17
    container_name: grafana
    ports:
      - 3002:3000
    restart: unless-stopped
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=grafana
    networks:
        extern1:
            aliases:
                - nerve_grafana              
    volumes:
      - grafana_ds:/etc/grafana/provisioning/datasources
volumes:
  db_data:
  grafana_ds:
networks:
  extern1:
    external: true

Refer to the official Docker Compose documentation for more information on writing compose files.