Skip to content

Docker Compose File Requirements

Version Specification

The last compatible version of the Docker Compose Specification is 3.8. Although the most up to date is the new Compose Specification Reference, it is preferred to stay with versions 3.7 and above to maintain compatibility.

Using versions above 3.0, it is important to run docker-compose in compatibility mode. Those versions have specifications for running Docker Swarm environments. Because we are running in standalone mode, the compatibility flag has to be enabled.

$ docker-compose --compatibility -f file1 -f file2 -f fileN up

About Logging Options Configurations

Currently, Docker Runtime is configured to redirect logs to the system journal where they are scraped by a Fluent-Bit instance. This includes the server logs and all container logs. Any configuration of the log driver within compose files should be avoided. As this logging driver works with TCP sockets, any configuration used for Files Logging Drivers (like local or json-file), such as max-size, max-file or compress shall not be used as those options are incompatible with TCP Socket Logging drivers. Explicit configuration of a container to use other logging sinks (such as null) that override the Docker runtime configuration should be done with caution.

Naming

The container name in the .yml shall be the exact string of the application name registered with the configuration manager with “_0” as a suffix.

The HCC2 does not yet support creating multiple instances.

Run the Container in Read Only

To reduce the number of write operation in the containers partition, run all containers in read-only mode. It is important to detect which folders the application tries to write to, and put those folders on a TMPFS mount (volatile data). see Rules and Best Practices | Persistent Data for information on how to store non-volatile data.

Info

https://github.com/compose-spec/compose-spec/blob/master/spec.md#read_only
Compose file version 3 reference

Container Restart Policy

If the container is part of the core services and this container should be live most of the time, we recommend to set up a policy to restart the container on failure. This way, Docker will try to restart the container if the application fails.

Dependencies Among Containers

If the container depends on another container, it should query that container to see if it is available and wait for the required services to be running. Explicit depends_on instructions are forbidden in the HCC2 for a number of reasons.

  • It makes it nearly impossible for docker-compose to independently start or stop containers, complicating device management
  • It significantly impacts startup/shutdown time
  • Using depends_on causes a false sense of security and poor habits. There is still the initialization period where the dependency container has been started by Docker but not yet available. A communication endpoint might not be ready so it is best to design an application in a resilient way to allow for other services not being available

DO NOT link services using the depends_on instruction

services:
  unity:
    depends_on:
      - configmgr
...

Info

https://docs.docker.com/compose/compose-file/compose-file-v3/#depends_on

Network Port Mapping

This section describes what to do if a port from the container is exposed to the host. This information is useful for containers that interact with the web servers or web applications. On the other hand, if the container does not have to expose any port to the host, then the practice is discouraged.

Info

https://docs.docker.com/compose/compose-file/compose-file-v3/#ports

Firewall

The HCC2 has a firewall. To be accessible from the outside, it is required to both expose any ports that need to be visible from the outside AND ensure the ports are added to the firewall. This feature will be documented here and in the user manual as appropriate when it is released.

Resource Limits

If the container should set explicit limits on its CPU and memory resource usage. If the service must have resources reserved for operations, then use deploy.resources.reservations. For more details, refer to Resource Limits

---
services:
  unity:
    deploy:
      resources:
        limits:
          cpu: "1.0"          # use up to 1 CPU core
          memory: "268435456" # use up to 256MB of RAM
...

Info

https://docs.docker.com/compose/compose-file/compose-file-v3/#resources

Environment Variables

The use of environment variables is suggested if the containerized application needs configurable arguments or parameters at launch. The use of environment variables allows you to change the values of parameters through the YAML file without rebuilding the container. Refer to Rules and Best Practices | Setup via Environment variables and Parameters

Info

https://docs.docker.com/compose/compose-file/compose-file-v3/#environment

Network and Volume Naming

For Docker networks and volumes that will be interacting with the container, it is important to use a unique name in the Compose file and avoid use of generic names such as network1 or volume1. The use of generic names for networks and volumes can cause a problem at the merging stage of the docker-compose command, when it loads all the compose files needed to form a service. Any network or volume will be created automatically when docker-compose runs. If the docker-compose shuts down a described service, the persistent volumes will not be deleted. It is recommended to prefix volume names with the name of the container it belongs to. In the case of shared volumes, care should be taken to ensure it will be unique and known to the containers accessing it.

Warning

All containers on the internal HCC2 bus communicate over the EdgeNet network. Any app interacting with this network must include it on it's networks list

Tip

The service that executes all the compose files scans for defined networks and initializes them to ensure they are started EXACTLY ONCE, before any containers start. This means containers must indicate external: true for all custom networks. See the example below.

References

Full Compose File Example

---
version: "3.7"

services:
  unity:
    image: qratehcc2sdk.azurecr.io/unity_top:#BUILD_NUMBER#
    container_name: unity_0
    read_only: true
    restart: on-failure
    networks:
      - edgenet
    ports:
      - '8443:8443/tcp'
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: "268435456"
    volumes:
      - configmgr_unity_vol:/shared/update
    tmpfs:
      - /home/node:uid=1000,gid=1000
      - /opt/unity_top/server/logs:uid=1000,gid=1000
      - /opt/unity_top/node_modules/.cache:uid=1000,gid=1000
      - /tmp
    environment:
      - CFG_MGR_IP=tcp://configmgr:5000

networks:
  edgenet:
    external: true

volumes:
  configmgr_unity_vol:
    name: configmgr_unity_vol
...