Docker Compose Files

Docker Tools

Docker and Docker Compose are used to manage the Edge Xpert Services.

Using Docker

For information on installing Docker, refer to Installation.

The Edge Xpert microservices are deployed in Docker containers.

For information on the Docker commands, refer to the Docker CLI documentation

Using Docker Compose

For information on installing Docker Compose, refer to Installation.

Edge Xpert uses Docker Compose to obtain and configure the latest images and to install, start the stop the microservice containers.

The docker-compose YAML files drive the edgexpert CLI tool. For further information on the Docker Compose YAML file see Configuration Files and Using a Local Docker Compose File.

For information on the Docker Compose commands, refer to the Docker Compose CLI documentation.

Configuration Files

Edge Xpert installs the Docker Compose and Application Service YAML files to /etc/edgexpert/. These files contain the configuration settings used by Edge Xpert.

The following Docker Compose YAML files are provided:

To view the content, open the file in a text editor.

IOTech recommends that you use [Docker Compose Override] if you need to make any changes.

For further information on the Docker Compose file, refer to the Compose file reference. For further information on using a local Docker Compose file within Edge Xpert, see Using a Local Docker Compose File.

Docker Compose Override

For more information on the docker-compose file content and parameters see Configuration File Content.

If you want to make changes to the configuration, it is best practice to override only the specific settings that should be changed in a local YAML file.

Using a Local Docker Compose File

To override the Docker Compose file, complete the following steps:

1. Create the necessary YAML files you wish to override from /etc/edgexpert in your chosen local directory. For example, ~/local-compose/docker-compose.yml
2. Open the local YAML file in an editor

3. Override the existing settings, or add your own configuration settings, as required.

   This example of a local docker-compose.yml demonstrates overriding the log level configuration with the environment variable WRITABLE_LOGLEVEL:

   version: '3.7'
   services:
     device-virtual:
       environment:
         WRITABLE_LOGLEVEL: DEBUG
   

   Note

   The above configuration changes the log level to DEBUG. This can generate a large number of log lines and is only advised when attempting to debug. The default is INFO.

4. Save the local docker-compose.yml file

Run Edge Xpert with a Local Docker Compose File

If using local Docker Compose files, you must run the edgexpert CLI commands from the directory containing your local YAML files.

The following message at the start of the output indicates that a local Docker Compose file is being used:

$ edgexpert up
Overriding configuration with local docker-compose.yml

Docker Compose File Precedence

Edge Xpert leverages the docker-compose override mechanism to simplify the effort for user to modify the configuration files.

If configuration files exist in EDGEXPERT_COMPOSE_PATH or the local directory, Edge Xpert will try to override base configuration with those files. The priority is as follows:
1. local (current) directory
2. EDGEXPERT_COMPOSE_PATH
3. default directory (/etc/edgexpert)

This rule applies on docker-compose.yml, docker-compose-security.yml and docker-compose.<EDGEXPERT_PROJECT>.yml.

For example:

$ export EDGEXPERT_COMPOSE_PATH=scripts/composefiles
$ export EDGEXPERT_PROJECT=prod
$ edgexpert up --secret

Overriding configuration with /home/user/scripts/composefiles/docker-compose.yml
Overriding configuration with local docker-compose.prod.yml
Creating network "edgexpert_edgex-network" with driver "bridge"
...

Environment Variable

Edge Xpert, as per the underlying Docker Compose Tool, allows the user to substitute environment variables in the configuration files from the shell or with an .env file.

By default Edge Xpert reads the .env file located under /etc/edgexpert/. Use the --env-file option to specify the location of an alternate environment file.

Generating a Docker Compose File

To generate a minimal docker compose file that defines only a specific set of microservices required for a particular use case, use the config gen command.

$ edgexpert config gen -h

Usage:  edgexpert config gen [OPTION] [SERVICES...]

Generate the Edge Xpert docker-compose file

Options:
      --api-gateway      Include the secret store and api gateway services
      --no-core          Include the specified services without the default services
      --no-core-data     Include the specified services without core-data
      --no-core-keeper   Include the specified services without core-keeper
  -o, --out string       Generated Docker Compose output file name (default "docker-compose-edgexpert.yml")
      --secret           Include the secret store services

For example, the following command generates a docker compose file that defines the Edge Xpert Core Services, the Virtual Device Service, the Edge Xpert Manager UI and the System Management Service:

edgexpert config gen device-virtual xpert-manager sys-mgmt

Then to start the Edge Xpert services using the generated docker compose file:

$ docker compose -f docker-compose-edgexpert.yml up -d

[+] Running 15/15
 ⠿ Network edgexpert_edgex-network        Created                                                                                         0.0s
 ⠿ Volume "edgexpert_xpert-manager-data"  Created                                                                                         0.0s
 ⠿ Volume "edgexpert_db-data"             Created                                                                                         0.0s
 ⠿ Volume "edgexpert_asc-config"          Created                                                                                         0.0s
 ⠿ Volume "edgexpert_mosquitto-data"      Created                                                                                         0.0s
 ⠿ Volume "edgexpert_mosquitto-log"       Created                                                                                         0.0s
 ⠿ Container core-keeper                  Started                                                                                         1.6s
 ⠿ Container core-data                    Started                                                                                         1.3s
 ⠿ Container core-metadata                Started                                                                                         1.9s
 ⠿ Container mqtt-broker                  Started                                                                                         1.8s
 ⠿ Container redis                        Started                                                                                         1.1s
 ⠿ Container sys-mgmt                     Started                                                                                         1.8s
 ⠿ Container device-virtual               Started                                                                                         1.8s
 ⠿ Container core-command                 Started                                                                                         1.8s
 ⠿ Container xpert-manager                Started                                                                                         2.0s