Skip to content

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.


  • Public Docker Hub registry


  • Private registry with authentication and a tag at the end


For services that offer a web UI or visualization, define a port in the range of 8500 — 8600 in the compose file to have a web UI link appear in the workload management section of the Local UI.

Web UI links

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"
 - networks:
         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
- /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
      - NGINX_PORT=${NGINX_PORT:-81}
      - "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:

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.

    Docker workload

  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.

    New version

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

    Category Settings and descriptions
    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.

    Compose file added


    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

Category Settings and descriptions
A name for the workload version. This could be a reminder for a certain configuration.
Example: Unlimited as a name for a Node-RED version that has unlimited access to CPU resources.

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.7.
Note that the image paths need to be included in the compose file. Refer to Docker Compose file for more information.

If labels have been defined and assigned to nodes, add them as selectors to the workload. When deploying a workload, the list of nodes will be filtered automatically to the specified label. Select the Insert label field to see a list of available labels.

Mark as released
Tick this checkbox to mark this workload as released. Once marked as released, the workload cannot be edited anymore.

Registries and Services tab

Category Settings and descriptions
REGISTRIES This column contains a list of registries defined in the compose file. Every registry entry has two fields where a Username and a Password can be entered. If the registry is password protected, credentials need to be entered for the image download and therefore the provisioning of the workload to proceed. Note that passwords are not stored.
SERVICES Search bar
Enter a search term to filter the list of services by name.

List of services
Each service listed in the Docker Compose file occupies one row in the list. The information of each column shows the following:
  • Name
    This is the name of the service as defined in the compose file.
  • Image name
    This is the image name in the format of registry:tag.
  • Image file (optional)
    Select the upward arrow to upload an image file from the local workstation. The uploaded image overrides the image defined in the compose file. However, note that defining an image path is still required.
    Obtain a Docker image for the upload by executing a command on the workstation where the Docker image for provisioning is located. Enter docker save <image_name> -o <filename>. Then in the Management System select the upward arrow symbol to open the file browser and upload the resulting <filename> Docker image. Also, do not upload Docker images in TAR.GZ format. This will produce a Docker workload file in the wrong format when the workload is exported.
  • Configuration storage
    A drop-down menu appears when one or more volumes are defined for a service in the compose file. Select a volume from the drop-down menu to designate the volume for storage of configuration files and enable the application of configuration files. The default selection is None. Refer to Applying configuration files to a workload for more information.
  • Restart on conf. update
    A checkbox appears when one ore more volumes are defined for a service in the compose file. Tick this checkbox to trigger an automatic restart of the service when configuration files are applied. Note that this only applies if a volume has been selected for configuration storage.

Remote connections tab

Category Settings and descriptions
REMOTE CONNECTIONS Select the Remote connections tab to configure a remote connection to the workload. Make sure to configure the workload first so that a remote connection can be established. Note that for Docker Compose workloads the service needs to be specified in addition.

Refer to Remote connections for more information and instructions for all remote connection types.

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'
    image: postgres:alpine
      - POSTGRES_USER=admin
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=postgres
    restart: always
      - db_data:/var/lib/postgresql/data
      - 5432
    image: grafana/grafana:7.5.17
    container_name: grafana
      - 3002:3000
    restart: unless-stopped
                - nerve_grafana              
      - grafana_ds:/etc/grafana/provisioning/datasources
    external: true

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