does readme have to be all CAPS?

roles/docker/readme.md

@@ -0,0 +1,139 @@
+docker
+======
+
+This role will install Docker and given a list of containers to deploy, will do the following:
+
+1. Create needed docker networks
+2. Open up necessary firewall ports
+3. Generate docker-compose files (1 per container)
+4. Ensure container user/group exists
+5. Ensure container persistent directories exist with correct perms and SELinux contexts
+6. Generate a systemd service file per container
+7. Setup systemd timers to automatically pull new and purge old container images
+
+Requirements
+------------
+
+This role is only tested on Fedora/CentOS machines.
+
+Variables
+---------
+
+`container_user`: user name to run containers as (will be generated if not exists)<br>
+`container_uid`: uid of above user name<br>
+`container_group`: group name of container_user<br>
+`container_gid`: gid of above group name<br>
+
+Automated pulls and purges are handled by systemd timers. Any valid [systemd timer calendar event expression](https://www.freedesktop.org/software/systemd/man/systemd.timer.html#OnCalendar=) may be passed to them:
+
+`docker_pull_timer`: weekly<br>
+`docker_purge_timer`: monthly
+
+    global_env_vars: # will be set on any container which has include_global_env_vars: true
+      - PUID={{ container_uid }}
+      - PGID={{ container_gid }}
+      - TZ=America/Los_Angeles
+
+    firewall_ports: # list of ports to open up on the host
+      - 80/tcp
+      - 443/tcp
+
+Since this role sets up each container individually, if multiple containers need to talk directly to each other container networks must be outlined:
+
+This role sets up each container as an individual docker-compose.yml file with a 1-to-1 relationship with it's systemd service. This means we can not rely on docker-compose's built-in networking feature for connecting multiple containers together.
+
+Outline any networks you need via container_networks:
+
+    container_networks:
+      - name: nginx-proxy
+        driver: bridge
+        subnet: 172.21.10.0/24
+        ip_range: 172.21.10.0/24
+        gateway: 172.21.10.1
+
+And specify those networks in the corresponding container's dictionary:
+
+    containers:
+      - name: swag
+        active: true
+        image: linuxserver/swag
+        ports:
+          - 80:80
+          - 443:443
+        volumes:
+          - /opt/swag:/config
+        include_global_env_vars: true
+        environment:
+          - URL=myexamplesite.biz
+          - VALIDATION=http
+          - SUBDOMAINS=www,git,
+          - EMAIL=admin@myexamplesite.biz
+        restart: unless-stopped
+        memlimit: 300m
+        networks:
+          - nginx-proxy
+
+        - name: gogs
+          active: true
+          image: gogs/gogs
+          ports:
+            - "10022:22" # https://github.com/go-yaml/yaml/issues/34#issuecomment-55772666
+          volumes:
+            - /opt/gogs:/data
+          include_global_env_vars: false
+          restart: unless-stopped
+          memlimit: 500m
+          networks:
+            - nginx-proxy
+
+
+Usage
+-----
+
+This role creates docker-compose.yml files for each entry in the list of containers under the filename:<br>
+`/root/docker/<name>/docker-compose.yml`
+
+It also generates systemd services files of the name:<br>
+`/etc/systemd/system/<name>.service`
+
+This file is a simple wrapper around docker-compose:
+
+    [root@shareunderware ~]# systemctl cat swag.service
+    # /etc/systemd/system/swag.service
+    # This file is managed by Ansible. Any local changes may be wiped out!
+    [Unit]
+    Description=systemd wrapper around docker swag service
+    Requires=docker.service
+    After=docker.service
+
+    [Service]
+    Restart=always
+    User=root
+    Group=docker
+
+    ExecStartPre=/usr/bin/docker-compose -f /root/docker/swag/docker-compose.yml down -v
+    ExecStart=/usr/bin/docker-compose -f /root/docker/swag/docker-compose.yml up
+    ExecStop=/usr/bin/docker-compose -f /root/docker/swag/docker-compose.yml down -v
+
+    [Install]
+    WantedBy=multi-user.target
+
+This method allows the logs to be captured via journald and can be queried just like any other service:
+
+    [root@shareunderware ~]# journalctl -fu swag.service 
+    Apr 25 04:20:59 shareunderware docker-compose[1956]: swag    | [cont-init.d] 70-templates: exited 0.
+    Apr 25 04:20:59 shareunderware docker-compose[1956]: swag    | [cont-init.d] 90-custom-folders: executing...
+    Apr 25 04:20:59 shareunderware docker-compose[1956]: swag    | [cont-init.d] 90-custom-folders: exited 0.
+    Apr 25 04:20:59 shareunderware docker-compose[1956]: swag    | [cont-init.d] 99-custom-files: executing...
+    Apr 25 04:20:59 shareunderware docker-compose[1956]: swag    | [custom-init] no custom files found exiting...
+    Apr 25 04:20:59 shareunderware docker-compose[1956]: swag    | [cont-init.d] 99-custom-files: exited 0.
+    Apr 25 04:20:59 shareunderware docker-compose[1956]: swag    | [cont-init.d] done.
+    Apr 25 04:20:59 shareunderware docker-compose[1956]: swag    | [services.d] starting services
+    Apr 25 04:20:59 shareunderware docker-compose[1956]: swag    | [services.d] done.
+    Apr 25 04:21:03 shareunderware docker-compose[1956]: swag    | Server ready
+
+
+License
+-------
+
+GPLv3