Skip to content
This repository has been archived by the owner on Aug 26, 2021. It is now read-only.

Docker Compose Support

Jump to bottom
Igor edited this page Aug 26, 2016 · 8 revisions

Intro

Docker Compose

Docker Compose is a tool that lets you define complex multi-container applications in YAML formatted text files (usually named docker-compose.yml) and then deploy these application with a single simple command:

docker-compose up

In the docker-compose file it is possible to define multiple services (containers) with their specific properties (e.g. volume mounts port mappings, links, etc.). Is is also possible to specify a Docker file that defines how to build specific images that cannot be found in existing registries.

Docker Compose in Admiral

It is possible to import docker-compose templates in Admiral by navigating to the templates view and clicking on the "Import template or Docker Compose" button.

Import docker-compose template in Admiral

You will be prompted to either to upload the docker-compose template or to enter its contents yourself. Both options lead to the same result - after pressing the import button, the docker-compose is converted to a template and stored in Admiral. However, the current version of Admiral started its development when there was no networking in Docker. Since networking is now the recommended way to provide means of communication between containers, most of the docker-compose files that one may find on the Internet (e.g. in Docker hub containers' documentation) need some slight modifications to work correctly in Admiral. In the following sections the differences between standard and Admiral supported docker-compose files will be discussed.

Differences between current Docker Compose and Admiral

In all of the following, only Docker Compose file format version 2 is considered.

Admiral supports only single-file docker-compose templates

This means that the following are currently not going to work:

  • Define environment variables in separate .env file
  • Splitting docker-compose file in separate files that extend one another
  • Other similar use-cases

It is not possible to build images in Admiral

In Docker Compose there is an option to specify instructions on how to build a specific image that cannot be found in existing registries by using the build key. In the simplest case, the value of this key is the path to the build context (e.g. directory that contains a Dockerfile). In Admiral building images is not possible as this feature makes more sense for development and testing purposes. The recommended way to deal with compose files the build key is to actually build the images and push them to a registry that is accessible from all Docker hosts.

Admiral 0.5.0 targets Docker without networking (Networking supports coming in next version)

Thus, features like the network_mode and networks keys that were introduced in the Docker Compose file format version 2 will not work. However, the newly added multi-host container communication Docker feature comes out of the box with Admiral. It is possible, for example, to have a front-end container that runs on host1 and connects to a database that runs on host2.

Since file format version 2, Docker Compose Networking was introduced. Basically, for each application that is defined by a docker-compose file, a new network is created. All of the services (containers) of this application join this network. These services are all accessible and can all be discovered on hostnames that match the service name (e.g. service1 can talk to service2 by connecting to 'service2'). This means that all container ports that are exposed by the EXPOSE command in the corresponding Docker files are now accessible by all services in the application without the need of using the links and ports keys in the docker-compose file. However, Admiral 0.5 does not support docker networking and instead provides its own solution for inter-container communication that is based on proxying the communication through a system container. This will work correctly only if:

  • all container2container dependencies are explicitly declared with the links key (so the system container will know which other containers to allow to communicate with one another)
  • all exposed ports of containers are declared with the ports key (so the system container knows what routing rules to apply)
    • here is a feature in Admiral - consider containers A and B. B listens on container port X and wants to connect to B. In Admiral it is possible to map X to a random host port but have A connect to B on port X. This is accomplished by the system container that listens on port X and relays the communication to the right port on B.

Publishing container port X to the same host port X is not supported in Admiral

Publishing port X of container C to the same host port X is possible, but may lead to unwanted behavior of applications. With the current networking implementation, this action will result in the container C and the system container (cmp_agent_core) trying to listen on the same port X. This is a known issue and will be fixed with the upcomming networking improvements. Until then, please refrain from publishing container port to the host port with the same number. You could chose an arbitary host port that does not coincide with any container port or let Admiral automatically chose a free host port.

Docker Compose file modifications in examples

Wordpress template

The current Wordpress docker-compose template can be found on https://hub.docker.com/_/wordpress/:

Original Wordpress docker-compose.yml

version: '2'
 
services:
 
  wordpress:
    image: wordpress
    ports:
      - 8080:80
    environment:
      WORDPRESS_DB_PASSWORD: example
 
  mysql:
    image: mariadb
    environment:
      MYSQL_ROOT_PASSWORD: example

This template can be successfully imported and even provisioned in Admiral. However, this template implies that wordpress and mysql services are in the same Docker network, so wordpress will be able to connect to mariadb using th mysql hostname. Since Admiral currently does not support Docker Compose networking, the deployed wordpress container will not be able to connect to the mysql service, because it will not be aware of its existence. Thus, a links key must be added that links wordpress to mysql. Also, the Dockerfile of wordpress exposes port 80 and the Dockerfile of mariadb exposes port 3306. The latter needs to be specified in the docker-compose file so the system container will know how to connect to this one. Port 80 is already in the docker-compose file, as this is the application's entry point.

Below is shown the modified version of the docker-compose file that can be imported in Admiral and will result in a working provisioned wordpress application. All the mandatory changes are documented with a Added for Admiral comment. Additionally, the container port 80 of wordpress container has been mapped to a random host port (and not 8080) so multiple instances of this application could be provisioned on the same host.

Modified Wordpress docker-compose.yml

version: '2'
 
services:
 
  wordpress:
    image: wordpress
#   Mapped to random host port instead of 8080 (optional)
    ports:
      - 80
    environment:
      WORDPRESS_DB_PASSWORD: example
#   Added for Bellevue
    links:
      - mysql
 
  mysql:
    image: mariadb
    environment:
      MYSQL_ROOT_PASSWORD: example
#   Added for Bellevue
    ports:
      - 3306

Using Admiral

Contributing

Clone this wiki locally