Merge pull request #530 from oliv3r/doc/better_env

Emphazise the need for properly setup environment variables

Author: buchdag

README.md

@@ -76,6 +76,12 @@ $ docker run -d --name nginx-gen --volumes-from nginx \
    -t nginxproxy/docker-gen -notify-sighup nginx -watch -only-exposed /etc/docker-gen/templates/nginx.tmpl /etc/nginx/conf.d/default.conf
 ```
 
+Start a container, taking note of any Environment variables a container expects. See the top of a template for details.
+
+```
+$ docker run --env VIRTUAL_HOST='example.com' --env VIRTUAL_PORT=80 ...
+```
+
 ===
 
 ### Usage
@@ -206,7 +212,7 @@ e75a60548dc9 = 1  # a key can be either container name (nginx) or ID
 
 ### Templating
 
-The templates used by docker-gen are written using the Go [text/template](http://golang.org/pkg/text/template/) language. In addition to the [built-in functions](http://golang.org/pkg/text/template/#hdr-Functions) supplied by Go, docker-gen uses [sprig](https://masterminds.github.io/sprig/) and some additional functions to make it simpler (or possible) to generate your desired output.
+The templates used by docker-gen are written using the Go [text/template](http://golang.org/pkg/text/template/) language. In addition to the [built-in functions](http://golang.org/pkg/text/template/#hdr-Functions) supplied by Go, docker-gen uses [sprig](https://masterminds.github.io/sprig/) and some additional functions to make it simpler (or possible) to generate your desired output. Some templates rely on environment variables within the container to make decisions on what to generate from the template.
 
 #### Emit Structure
 
@@ -411,10 +417,10 @@ Start nginx-proxy:
 $ docker run -d -p 80:80 -v /var/run/docker.sock:/tmp/docker.sock -t nginxproxy/nginx-proxy
 ```
 
-Then start containers with a VIRTUAL_HOST env variable:
+Then start containers with a VIRTUAL_HOST (and the VIRTUAL_PORT if more than one port is exposed) env variable:
 
 ```
-$ docker run -e VIRTUAL_HOST=foo.bar.com -t ...
+$ docker run -e VIRTUAL_HOST=foo.bar.com -e VIRTUAL_PORT=80 -t ...
 ```
 
 If you wanted to run docker-gen directly on the host, you could do it with:

templates/dnsmasq.hosts.conf.tmpl

@@ -1,3 +1,6 @@
+{{/* Simple dnsmasq template generating host entries */}}
+{{/* Domains are hard-coded, replace 'docker.comany.com' below */}}
+
 {{$domain := "docker.company.com"}}
 {{range $key, $value := .}}
 # {{ $value.Name }} ({{$value.ID}} from {{$value.Image.Repository}})

templates/etcd.tmpl

@@ -1,3 +1,4 @@
+{{/* etcd template to generate registration script */}}
 
 #!/bin/bash
 

templates/fluentd.conf.tmpl

@@ -1,3 +1,4 @@
+{{/* Generates fluentd configuration entries */}}
 
 ## File input
 ## read docker logs with tag=docker.container

templates/logrotate.tmpl

@@ -1,3 +1,7 @@
+{{/* Generate logrotate snippets for logrotate based on files listed in */}}
+{{/* the comma separated environment variable LOG_FILES */}}
+{{/* e.g. docker run --env='/var/log/messages,/var/log/lastlog' ... */}}
+
 {{ range $index, $value := $ }}
 {{ $logs := $value.Env.LOG_FILES }}
 {{ if $logs }}

templates/nginx.tmpl

@@ -1,3 +1,8 @@
+{{/* default nginx configuration template */}}
+{{/* Generate a configuration file based on the containers mandatory */}}
+{{/* VIRTUAL_HOST environment variable and the exposed ports. If multiple */}}
+{{/* ports are exposed, the first one is used, unless set with VIRTUAL_PORT */}}
+
 server {
 	listen 80 default_server;
 	server_name _; # This is just an invalid value which will never trigger on a real hostname.
@@ -13,7 +18,7 @@ upstream {{ $host }} {
 
 	{{ $addrLen := len $value.Addresses }}
 	{{ $network := index $value.Networks 0 }}
-	
+
 	{{/* If only 1 port exposed, use that */}}
 	{{ if eq $addrLen 1 }}
 		{{ with $address := index $value.Addresses 0 }}
@@ -62,4 +67,4 @@ server {
 		proxy_set_header Connection "";
 	}
 }
-{{ end }}
+{{ end }}