Skip to content

Commit e955802

Browse files
jwilderjwilder
committed
Update docs
1 parent 8fbfe04 commit e955802

File tree

2 files changed

+103
-27
lines changed

2 files changed

+103
-27
lines changed

‎README.md

Lines changed: 58 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,22 @@ docker-gen
33

44
`docker-gen` is a file generator that renders templates using docker container meta-data.
55

6-
docker-gen can be used to generate various kinds of files for:
6+
It can be used to generate various kinds of files for:
77

8-
* **Centralized logging** - fluentd, logstash or other centralized logging tools that tail the containers JSON log file or files within the container.
9-
* **Log Rotation** - logrotate files to rotate container JSON log files
10-
* **Reverse Proxy Configs** - nginx, haproxy, etc. reverse proxy configs to route requests from the host to containers
11-
* **Service Discovery** - Scripts (python, bash, etc..) to register containers within etcd, hipache, etc..
8+
* **Centralized logging** - [fluentd](https://github.com/jwilder/docker-gen/blob/master/templates/fluentd.conf.tmpl), logstash or other centralized logging tools that tail the containers JSON log file or files within the container.
9+
* **Log Rotation** - [logrotate](https://github.com/jwilder/docker-gen/blob/master/templates/logrotate.tmpl) files to rotate container JSON log files
10+
* **Reverse Proxy Configs** - [nginx](https://github.com/jwilder/docker-gen/blob/master/templates/nginx.tmpl), [haproxy](https://github.com/jwilder/docker-discover), etc. reverse proxy configs to route requests from the host to containers
11+
* **Service Discovery** - Scripts (python, bash, etc..) to register containers within [etcd](https://github.com/jwilder/docker-register), hipache, etc..
1212

1313
===
1414

1515
### Installation
1616

17+
There are three common ways to run docker-gen:
18+
* on the host
19+
* bundled in a container with another application
20+
* separate standalone containers
21+
1722
#### Host Install
1823

1924
Linux binaries for release [0.3.4](https://github.com/jwilder/docker-gen/releases)
@@ -29,20 +34,48 @@ $ tar xvzf docker-gen-linux-amd64-0.3.4.tar.gz
2934
$ ./docker-gen
3035
```
3136

32-
#### Container Install
37+
#### Bundled Container Install
38+
39+
Docker-gen can be bundled inside of a container along-side and applications.
40+
41+
[jwilder/nginx-proxy](https://index.docker.io/u/jwilder/nginx-proxy/) trusted build is an example of
42+
running docker-gen within a container along-side nginx.
43+
[jwilder/docker-register](https://github.com/jwilder/docker-register) is an example or running
44+
docker-gen within a container to do service registration with etcd.
45+
46+
#### Separate Container Install
47+
48+
It can also be run as two separate containers using the [jwilder/docker-gen](https://index.docker.io/u/jwilder/docker-gen/)
49+
image virtually any other image.
50+
51+
This is how you could run the official [nginx](https://registry.hub.docker.com/_/nginx/) image and
52+
have dockgen-gen generate a reverse proxy config in the same way that `nginx-proxy` works. You may want to do
53+
this to prevent having the docker socket bound to an publicly exposed container service.
3354

34-
See [jwilder/nginx-proxy](https://index.docker.io/u/jwilder/nginx-proxy/) trusted build as an example of running docker-gen within a container.
55+
Start nginx with a shared volume:
56+
57+
```
58+
$ docker run -d -p 80:80 --name nginx -v /tmp/nginx:/etc/nginx/conf.d -t nginx
59+
```
60+
61+
Start the docker-gen container with the shared volume:
62+
```
63+
$ docker run --volumes-from nginx \
64+
-v /var/run/docker.sock:/tmp/docker.sock \
65+
-v $(pwd)/templates:/etc/docker-gen/templates
66+
-t docker-gen -notify-sighup nginx -watch --only-published /etc/docker-gen/templates/nginx.tmpl /etc/nginx/conf.d/default.conf
67+
```
3568

69+
===
3670

3771
### Usage
3872
```
3973
$ docker-gen
40-
Usage: docker-gen [options] <template> [<dest>]
74+
Usage: docker-gen [-config file] [-watch=false] [-notify="restart xyz"] [-notify-sighup="nginx-proxy"] [-interval=0] [-endpoint tcp|unix://..] <template> [<dest>]
4175
```
4276

43-
[-config file] [-watch=false] [-notify="restart xyz"] [-notify-sighup="nginx-proxy"] [-interval=0] [-endpoint tcp|unix://..]
44-
4577
*Options:*
78+
4679
```
4780
-config="": Use the specified config file instead of command-line options. Multiple templates can be defined and
4881
they will be executed in the order that they appear in the config file.
@@ -60,12 +93,15 @@ Usage: docker-gen [options] <template> [<dest>]
6093

6194
If no `<dest>` file is specified, the output is sent to stdout. Mainly useful for debugging.
6295

96+
===
6397

6498
### Examples
6599

66-
#### NGINX Reverse Proxy Config
100+
* [Automated Nginx Reverse Proxy for Docker](http://jasonwilder.com/blog/2014/03/25/automated-nginx-reverse-proxy-for-docker/)
101+
* [Docker Log Management With Fluentd](http://jasonwilder.com/blog/2014/03/17/docker-log-management-using-fluentd/)
102+
* [Docker Service Discovery Using Etcd and Haproxy](http://jasonwilder.com/blog/2014/07/15/docker-service-discovery/)
67103

68-
##### Containerized
104+
#### NGINX Reverse Proxy Config
69105

70106
[jwilder/nginx-proxy](https://index.docker.io/u/jwilder/nginx-proxy/) trusted build.
71107

@@ -76,27 +112,31 @@ $ docker run -d -p 80:80 -v /var/run/docker.sock:/tmp/docker.sock -t jwilder/ngi
76112
```
77113

78114
Then start containers with a VIRTUAL_HOST env variable:
115+
79116
```
80117
$ docker run -e VIRTUAL_HOST=foo.bar.com -t ...
81118
```
82119

83-
##### Host Install
120+
If you wanted to run docker-gen directly on the host, you could do it with:
84121

85122
```
86-
$ docker-gen -only-exposed -watch -notify "/etc/init.d/nginx reload" templates/nginx.tmpl /etc/nginx/sites-enabled/default
123+
$ docker-gen -only-published -watch -notify "/etc/init.d/nginx reload" templates/nginx.tmpl /etc/nginx/sites-enabled/default
87124
```
88125

89-
[Automated Nginx Reverse Proxy for Docker](http://jasonwilder.com/blog/2014/03/25/automated-nginx-reverse-proxy-for-docker/)
90-
91126
#### Fluentd Log Management
92127

128+
This template generate a fluentd.conf file used by fluentd. It would then ships log files off
129+
the host.
130+
93131
```
94132
$ docker-gen -watch -notify "restart fluentd" templates/fluentd.tmpl /etc/fluent/fluent.conf
95133
```
96134

97-
[Docker Log Management With Fluentd](http://jasonwilder.com/blog/2014/03/17/docker-log-management-using-fluentd/)
135+
#### Service Discovery in Etcd
136+
98137

99-
#### Register Containers in Etcd
138+
This template is an example of generating a script that is then executed. This tempalte generates
139+
a python script that is then executed which register containers in Etcd using it's HTTP API.
100140

101141
```
102142
$ docker-gen -notify "/bin/bash /tmp/etcd.sh" -interval 10 templates/etcd.tmpl /tmp/etcd.sh

‎templates/nginx.tmpl

Lines changed: 45 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,63 @@
1+
server {
2+
listen 80 default_server;
3+
server_name _; # This is just an invalid value which will never trigger on a real hostname.
4+
error_log /proc/self/fd/2;
5+
access_log /proc/self/fd/1;
6+
return 503;
7+
}
8+
19
{{ range $host, $containers := groupByMulti $ "Env.VIRTUAL_HOST" "," }}
210
upstream {{ $host }} {
311

412
{{ range $index, $value := $containers }}
5-
{{ with $address := index $value.Addresses 0 }}
6-
server {{ $address.IP }}:{{ $address.Port }};
13+
14+
{{ $addrLen := len $value.Addresses }}
15+
{{/* If only 1 port exposed, use that */}}
16+
{{ if eq $addrLen 1 }}
17+
{{ with $address := index $value.Addresses 0 }}
18+
# {{$value.Name}}
19+
server {{ $address.IP }}:{{ $address.Port }};
20+
{{ end }}
21+
22+
{{/* If more than one port exposed, use the one matching VIRTUAL_PORT env var */}}
23+
{{ else if $value.Env.VIRTUAL_PORT }}
24+
{{ range $i, $address := $value.Addresses }}
25+
{{ if eq $address.Port $value.Env.VIRTUAL_PORT }}
26+
# {{$value.Name}}
27+
server {{ $address.IP }}:{{ $address.Port }};
28+
{{ end }}
29+
{{ end }}
30+
31+
{{/* Else default to standard web port 80 */}}
32+
{{ else }}
33+
{{ range $i, $address := $value.Addresses }}
34+
{{ if eq $address.Port "80" }}
35+
# {{$value.Name}}
36+
server {{ $address.IP }}:{{ $address.Port }};
37+
{{ end }}
38+
{{ end }}
739
{{ end }}
840
{{ end }}
9-
1041
}
1142

1243
server {
13-
#ssl_certificate /etc/nginx/certs/demo.pem;
14-
#ssl_certificate_key /etc/nginx/certs/demo.key;
15-
1644
gzip_types text/plain text/css application/json application/x-javascript text/xml application/xml application/xml+rss text/javascript;
1745

1846
server_name {{ $host }};
1947
proxy_buffering off;
48+
error_log /proc/self/fd/2;
49+
access_log /proc/self/fd/1;
2050

2151
location / {
22-
proxy_pass http://{{ $host }};
23-
include /etc/nginx/proxy_params;
52+
proxy_pass http://{{ $host }};
53+
proxy_set_header Host $http_host;
54+
proxy_set_header X-Real-IP $remote_addr;
55+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
56+
proxy_set_header X-Forwarded-Proto $scheme;
57+
58+
# HTTP 1.1 support
59+
proxy_http_version 1.1;
60+
proxy_set_header Connection "";
2461
}
2562
}
26-
2763
{{ end }}

0 commit comments

Comments
 (0)