ruamel.dc2service 0.3.1
generate init configuration file (systemd/Upstart) from docker-compose.yml
License: MIT license
Keywords: docker-compose upstart systemd init service

==============
``dc2service``
==============

The ``dc2service`` utility generates configuration files for
``systemd``/``Upstart`` based on a single ``docker-compose`` YAML input file.

The init type is autodetected, but can be overruled from the command-line.

The service name is determinted by the ``container_name`` entries for all
the services in the YAML file. Each service **has to have** a ``container_name``
specified.

As ``docker-compose`` YAML file format doesn't allow for
extra metadata fields, two comment entries at the beginning of the
YAML file are parsed for a description and author.

If the version 2 YAML file format is used you should consider using
``ruamel.dcw`` as wrapper for ``docker-compose``, if you do the
comments are not necessary and you can specify ``author`` and
``description`` under the top level ``user-data`` key.

If external ports are specified (i.e. of the form "ip:ip") then the
external port numbers are extended to the description.

The file generation is template based and can easily be adjusted to your needs.
Their location can be viewed by doing ``dc2service templates``

Example version 2 input YAML file for Mongo DB 
----------------------------------------------

In a version 1 ``docker-compose.yml`` and using ``ruamel.dcw`` 
you can set the ``author`` and ``description`` conveniently as normal
key-value pairs, and also specify a default for environment variables::

  version: "2"
  user-data:
    author: Anthon van der Neut <a.van.der.neut@ruamel.eu>
    description: mongo container
    env-variables:
      DOCKER_MONGO_PORT: 27017
      DOCKER_MONGO_BASE_DIR: /data1/DB/mongo
  services:
    mongodb:
      container_name: mongo
      image: mongo:2.4
      volumes:
        - ${DOCKER_MONGO_BASE_DIR}:/data/db
        ports:
          - ${DOCKER_MONGO_PORT}:27017

.. example code docker-compose.yml


Example version 1 input YAML file for Mongo DB 
----------------------------------------------

As version 1 ``docker-compose.yml`` file for single service running
Mongo DB with an external (i.e. host oriented) port::

  # author: Anthon van der Neut <a.van.der.neut@ruamel.eu>
  # description: mongo container
  mongodb:
    container_name: mongo
    image: mongo:2.4
    volumes:
     - /data1/DB/mongo:/data/db
    ports:
    - 27017:27017

.. example code docker-compose-1.yml


``systemd``
-----------

The command ``dc2service --systemd generate /opt/docker/mongo/docker-compose.yml`` will
generate the file ``/etc/systemd/system/mongo-docker.service``::

  [Unit]
  Description=mongo container on port 27017
  # Author = Anthon van der Neut <a.van.der.neut@ruamel.eu> (dc2service 0.1.0.dev)
  Requires=docker.service
  After=docker.service

  [Service]
  Restart=always
  ExecStart=/opt/util/docker-compose/bin/docker-compose -f /opt/docker/mongo/docker-compose.yml up --no-recreate
  ExecStop=/opt/util/docker-compose/bin/docker-compose -f /opt/docker/mongo/docker-compose.yml stop

  [Install]
  WantedBy=multi-user.target

.. example code mongo-docker-1.service

If you have ``ruamel.dcw`` installed ``.../bin/docker-compose`` will be ``.../bin/dcw``

Upstart
-------

The command ``dc2service --upstart generate /opt/docker/mongo/docker-compose.yml`` will
generate the file ``/etc/init/mongo-docker.conf``::

  description "mongo container on port 27017"
  author "Anthon van der Neut <a.van.der.neut@ruamel.eu> (dc2service 0.1.0.dev)"
  start on filesystem and started docker
  stop on runlevel [!2345]
  respawn

  pre-start script
    /opt/util/docker-compose/bin/docker-compose -f /opt/docker/mongo/docker-compose.yml up -d --no-recreate
  end script

  script
    sleepWhileAppIsUp(){
      while docker ps --filter=name=mongo | grep -qF mongo ; do
        sleep 2
      done
    }

    sleepWhileAppIsUp
  end script

  post-stop script
    if docker ps --filter=name=mongo | grep -qF mongo; then
      /opt/util/docker-compose/bin/docker-compose -f /opt/docker/mongo/docker-compose.yml stop
    fi
  end script

.. example code mongo-docker-1.conf

If you have ``ruamel.dcw`` installed ``.../bin/docker-compose`` will be ``.../bin/dcw``


Expanding environment variables
-------------------------------

If you use environment variables in a version 1 docker-compose.yml
file in your YAML file they will be expanded if the are of the form
`${XYZ}`. The other form `$XYZ` is not expanded. You should however
consider installing ``ruamel.dcw`` and using the version 2 format as
that can handle the expansion dynamically and allow defaults to be
specified in the YAML file, as well as storing the environment variables for the
Dockerfile to use.

Expansion is only relevant for the parts that are copied (external
port numbers, name of container).

If you use this feature make sure that the environment variables are set in the
conf file. In ``systemd`` with::

  [Service]
  Environment=DOCKERIMAPPORT=143

and in Upstart::

  env DOCKERIMAPPORT=143

``dc2service`` will try to insert the right definitions for you.

**For version 2 files and when using ``ruamel.dcw`` this is not necessary and 
therefore not done**

Finding ``docker-compose``
--------------------------

As the full path to ``docker-compose`` or ``dcw`` will be inserted in
the configuration file, this path needs to be
available. ``dc2service`` will search
``/opt/util/docker-compose/bin/`` and the PATH environement variable
for the locations of ``dcw`` and ``docker-compose``. If your
``docker-compose`` is not in your path you can hand the full path in
with the option ``--docker-compose`` or specify this in the file
``~/.config/ruamel_dc2service/ruamel_dc2service.pon``::

  dict(
      glbl={'docker-compose': '/opt/util/docker-compose/bin/docker-compose'},
  )