=====
Usage
=====

Docker is a platform for developers and system administrators for developing,
shipping, and running applications. Docker enables you to quickly assemble
applications from components and eliminates the friction that can come when
shipping the code. Also, with Docker, you get your code tested and deployed
into production as fast as possible.

This file provides the sample configurations for different use cases.

Docker host configuration samples
=================================

* Docker host sample pillar configuration:

  .. code-block:: yaml

    docker:
      host:
        enabled: true
        options:
          bip: 172.31.255.1/16
          insecure-registries:
            - 127.0.0.1
            - 10.0.0.1
          log-driver: json-file
          log-opts:
            max-size: 50m

* Proxy configuration for Docker host:

  .. code-block:: yaml

    docker:
      host:
        proxy:
          enabled: true
          http: http://user:pass@proxy:3128
          https: http://user:pass@proxy:3128
          no_proxy:
            - localhost
            - 127.0.0.1
            - docker-registry


Docker Swarm configuration samples
==================================

Role can be master, manager, or worker. Master is the first manager that
will initialize the swarm.

* Metadata for manager (the first node):

  .. code-block:: yaml

    docker:
      host:
        enabled: true
      swarm:
        role: manager
        advertise_addr: 192.168.1.5
        bind:
          address: 192.168.1.5
          port: 2377

* Metadata for worker:

  .. code-block:: yaml

    docker:
      host:
        enabled: true
      swarm:
        role: worker
        master:
          host: 192.168.1.5
          port: 2377

The token to join to the master node is obtained from grains using
``salt.mine``.  In case of any ``join_token undefined`` issues, verify that
you have ``docker_swarm_`` grains available.

Docker client configuration samples
===================================

* Container:

  .. code-block:: yaml

    docker:
      client:
        container:
          jenkins:
            # Don't start automatically
            start: false
            restart: unless-stopped
            image: jenkins:2.7.1
            ports:
              - 8081:8080
              - 50000:50000
            environment:
              JAVA_OPTS: "-Dhudson.footerURL=https://www.example.com"
            volumes:
              - /srv/volumes/jenkins:/var/jenkins_home

* Docker compose:

  The states providing this functionality include:

  - docker.client.stack
  - docker.client.compose

  Stack is new and works with Docker Swarm Mode.
  Compose is legacy and works only if node is not a member of Swarm.
  Metadata for both states are similar and differs only in implementation.

  * Stack:

    .. code-block:: yaml

        docker:
          client:
            stack:
              django_web:
                enabled: true
                update: true
                environment:
                  SOMEVAR: somevalue
                version: "3.1"
                service:
                  db:
                    image: postgres
                  web:
                    image: djangoapp
                    volumes:
                      - /srv/volumes/django:/srv/django
                    ports:
                      - 8000:8000
                    depends_on:
                      - db

  * Compose

    You can install ``docker-compose`` using one of the following options:

    - Distribution package (default)
    - Using Pip
    - Using Docker container

    Install ``docker-compose`` using Docker (default is distribution package):

    .. code-block:: yaml

       docker:
         client:
           compose:
             source:
               engine: docker
               image: docker/compose:1.8.0
             django_web:
               # Run up action, any positional argument to docker-compose CLI
               # If not defined, only docker-compose.yml is generated
               status: up
               # Run image pull every time state is run triggering container
               # restart in case it's changed
               pull: true
               environment:
                 SOMEVAR: somevalue
               service:
                 db:
                   image: postgres
                 web:
                   image: djangoapp
                   volumes:
                     - /srv/volumes/django:/srv/django
                   ports:
                     - 8000:8000
                   depends_on:
                     - db

* Registry

  .. code-block:: yaml

    docker:
      client:
        registry:
          target_registry: apt:5000
          image:
            - registry: docker
              name: compose:1.8.0
            - registry: tcpcloud
              name: jenkins:latest
            - registry: ""
              name: registry:2
              target_registry: myregistry

Docker Service configuration samples
====================================

To deploy service in Swarm mode, you can use ``docker.client.service``:

.. code-block:: yaml

    parameters:
      docker:
        client:
          service:
            postgresql:
              environment:
                POSTGRES_USER: user
                POSTGRES_PASSWORD: password
                POSTGRES_DB: mydb
              restart:
                condition: on-failure
              image: "postgres:9.5"
              ports:
                - 5432:5432
              volume:
                data:
                  type: bind
                  source: /srv/volumes/postgresql/maas
                  destination: /var/lib/postgresql/data

Docker Service configuration samples with docker secrets
========================================================

To deploy service in Swarm mode using docker secrets, you can use
``docker.client.service``:

.. code-block:: yaml

    parameters:
      docker:
        client:
          service:
            postgresql:
              environment:
                POSTGRES_USER: user
                POSTGRES_PASSWORD_FILE: '/run/secrets/postgres'
                POSTGRES_DB: mydb
              secrets:
                - postgres
              restart:
                condition: on-failure
              image: "postgres:9.5"
              ports:
                - 5432:5432
              volume:
                data:
                  type: bind
                  source: /srv/volumes/postgresql/maas
                  destination: /var/lib/postgresql/data
          secrets:
            postgres:
              external: true
              value: password

Docker Registry configuration samples
=====================================

* Basic Docker Registry configuration:

  .. code-block:: yaml

    docker:
      registry:
        log:
          level: debug
          formatter: json
        cache:
          engine: redis
          host: localhost
        storage:
          engine: filesystem
          root: /srv/docker/registry
        bind:
          host: 0.0.0.0
          port: 5000
        hook:
          mail:
            levels:
              - panic
            # Options are rendered as yaml as is so use hook-specific options here
            options:
              smtp:
                addr: smtp.sendhost.com:25
                username: sendername
                password: password
                insecure: true
              from: name@sendhost.com
              to:
                - name@receivehost.com

* Docker login to private registry:

  .. code-block:: yaml

    docker:
      host:
        enabled: true
        registry:
          first:
            address: private.docker.com
            user: username
            password: password
          second:
            address: private2.docker.com
            user: username2
            password: password2

Docker container service management configuration samples
=========================================================

* Start a service in a container:

  .. code-block:: yaml

     contrail_control_started:
       dockerng_service.start:
         - container: f020d0d3efa8
         - service: contrail-control

  or

  .. code-block:: yaml

     contrail_control_started:
       dockerng_service.start:
         - container: contrail_controller
         - service: contrail-control

* Stop a service in a container:

.. code-block:: yaml

    contrail_control_stoped:
      dockerng_service.stop:
        - container: f020d0d3efa8
        - service: contrail-control

* Restart a service in a container:

.. code-block:: yaml

    contrail_control_restart:
      dockerng_service.restart:
        - container: f020d0d3efa8
        - service: contrail-control

* Enable a service in a container:

.. code-block:: yaml

    contrail_control_enable:
      dockerng_service.enable:
        - container: f020d0d3efa8
        - service: contrail-control

* Disable a service in a container:

.. code-block:: yaml

    contrail_control_disable:
      dockerng_service.disable:
        - container: f020d0d3efa8
        - service: contrail-control

Use registry that requires authentication
=========================================================

* Define private Docker registry and credentials for it:

  .. code-block:: yaml

    docker:
      host:
        insecure_registries:
          - 192.168.0.254:5000
      registry:
        my_registry:
          address: 192.168.0.254:5000
          user: registry_user
          password: registry_password

* Specify that services in stack require registry with authentication

  .. code-block:: yaml

    docker:
      client:
        stack:
          myapp:
            registry_auth: True

**Read more**

* https://docs.docker.com/installation/ubuntulinux/
* https://github.com/saltstack-formulas/docker-formula