Docker Compose File Requirements

• Version Specification
• About Logging Options Configurations
• Naming
• Run the Container in Read Only
• Container Restart Policy
• Dependencies to other Containers
• Network Port Mapping
• Resource Limits
• Environment Variables
• Network and Volume Naming
• References
  • Full Compose File Example
  • Links

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

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.

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

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.

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
...

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

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.

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