|
| 1 | +# Varnish Docker image |
| 2 | + |
| 3 | +Varnish docker image with support for dynamic backends, Rancher DNS, auto-configure |
| 4 | +and reload. |
| 5 | + |
| 6 | +This image is generic, thus you can obviously re-use it within |
| 7 | +your non-related EEA projects. |
| 8 | + |
| 9 | + - Debian Stretch |
| 10 | + - Varnish **4.1.11** |
| 11 | + - Varnish agent 2 **4.1.4** |
| 12 | + - Varnish dashboard |
| 13 | + - EXPOSE **6081 6085** |
| 14 | + |
| 15 | +## Supported tags and respective Dockerfile links |
| 16 | + |
| 17 | + - `:latest` [*Dockerfile*](https://github.com/eea/eea.docker.varnish/blob/master/varnish/Dockerfile) (Debian Stretch, Varnish 4.1) |
| 18 | + |
| 19 | +### Stable and immutable tags |
| 20 | + |
| 21 | + - `:4.1-6.4` [*Dockerfile*](https://github.com/eea/eea.docker.varnish/tree/4.1-6.4/varnish/Dockerfile) - Varnish: **4.1.11** Release: **6.4 |
| 22 | + - `:4.1-6.5` [*Dockerfile*](https://github.com/eea/eea.docker.varnish/tree/4.1-6.5/varnish/Dockerfile) - Varnish: **4.1.11** Release: **6.5 |
| 23 | + |
| 24 | +See [older versions](https://github.com/eea/eea.docker.varnish/releases) |
| 25 | + |
| 26 | +### Changes |
| 27 | + |
| 28 | + - [CHANGELOG.md](https://github.com/eea/eea.docker.varnish/blob/master/CHANGELOG.md) |
| 29 | + |
| 30 | +## Base docker image |
| 31 | + |
| 32 | + - [hub.docker.com](https://registry.hub.docker.com/u/eeacms/varnish) |
| 33 | + |
| 34 | +## Source code |
| 35 | + |
| 36 | + - [github.com](http://github.com/eea/eea.docker.varnish) |
| 37 | + |
| 38 | + |
| 39 | +## Installation |
| 40 | + |
| 41 | +1. Install [Docker](https://www.docker.com/). |
| 42 | + |
| 43 | + |
| 44 | +## Usage |
| 45 | + |
| 46 | +### Run with Docker Compose |
| 47 | + |
| 48 | +Here is a basic example of a `docker-compose.yml` file using the `eeacms/varnish` docker image: |
| 49 | + |
| 50 | + version: "2" |
| 51 | + services: |
| 52 | + varnish: |
| 53 | + image: eeacms/varnish |
| 54 | + ports: |
| 55 | + - "80:6081" |
| 56 | + - "6085:6085" |
| 57 | + depends_on: |
| 58 | + - anon |
| 59 | + - auth |
| 60 | + - download |
| 61 | + environment: |
| 62 | + BACKENDS: "anon auth download" |
| 63 | + BACKENDS_PORT: "8080" |
| 64 | + DNS_ENABLED: "true" |
| 65 | + BACKENDS_PROBE_INTERVAL: "3s" |
| 66 | + BACKENDS_PROBE_TIMEOUT: "1s" |
| 67 | + BACKENDS_PROBE_WINDOW: "3" |
| 68 | + BACKENDS_PROBE_THRESHOLD: "2" |
| 69 | + DASHBOARD_USER: "admin" |
| 70 | + DASHBOARD_PASSWORD: "admin" |
| 71 | + DASHBOARD_SERVERS: "varnish" |
| 72 | + DASHBOARD_DNS_ENABLED: "true" |
| 73 | + anon: |
| 74 | + image: eeacms/hello |
| 75 | + environment: |
| 76 | + PORT: "8080" |
| 77 | + auth: |
| 78 | + image: eeacms/hello |
| 79 | + environment: |
| 80 | + PORT: "8080" |
| 81 | + download: |
| 82 | + image: eeacms/hello |
| 83 | + environment: |
| 84 | + PORT: "8080" |
| 85 | + |
| 86 | + |
| 87 | +The application can be scaled to use more server instances as backends, with `docker-compose scale`: |
| 88 | + |
| 89 | + $ docker-compose up -d |
| 90 | + $ docker-compose scale anon=4 auth=2 varnish=2 |
| 91 | + |
| 92 | +An example of a more complex application using the `eeacms/varnish` with `docker-compose` |
| 93 | +image is [EEA WWW](https://github.com/eea/eea.docker.www). |
| 94 | + |
| 95 | + |
| 96 | +### Extend the image with a custom varnish.vcl file |
| 97 | + |
| 98 | +The `default.vcl` file provided with this image is bare and only contains |
| 99 | +the marker to specify the VCL version. If you plan on using a more |
| 100 | +elaborate base configuration in your container and you want it shipped with |
| 101 | +your image, you can extend the image in a Dockerfile, like this: |
| 102 | + |
| 103 | + FROM eeacms/varnish |
| 104 | + COPY varnish.vcl /etc/varnish/conf.d/ |
| 105 | + |
| 106 | +and then run |
| 107 | + |
| 108 | + $ docker build -t varnish-custom /path/to/Dockerfile |
| 109 | + |
| 110 | +### Support for specifying probe request headers |
| 111 | + |
| 112 | +Two environment variables support defining specific probe request headers. |
| 113 | +The primary warning / tricky part is around the delimiter used for separating |
| 114 | +the individual headers. Below is an example: |
| 115 | + |
| 116 | + BACKENDS_PROBE_REQUEST: 'GET / HTTP/1.1|Host: example.com|Connection: close|User-Agent: Varnish Health Probe' |
| 117 | + BACKENDS_PROBE_REQUEST_DELIMITER: '|' |
| 118 | + |
| 119 | +The above will result in the probe being specified using the probe.request attribute |
| 120 | +and will replace the default probe.url attribute completely. |
| 121 | +The important point, of course, is that you need to pick an appropriate delimiter |
| 122 | +that is not contained within any headers that you wish to pass. |
| 123 | + |
| 124 | +The hostname of the current backend being probed can be specify using the `%(hostname)s` placeholder: |
| 125 | + |
| 126 | + BACKENDS_PROBE_REQUEST: 'GET / HTTP/1.1|Host: %(hostname)s|Connection: close|User-Agent: Varnish Health Probe' |
| 127 | + BACKENDS_PROBE_REQUEST_DELIMITER: '|' |
| 128 | + |
| 129 | +### Change and reload configuration without restarting the container |
| 130 | + |
| 131 | +If the configuration directory is mounted as a volume, you can modify |
| 132 | +it from outside the container. In order for the modifications |
| 133 | +to be loaded by the varnish daemon, you have to run the `reload` command, |
| 134 | +as following: |
| 135 | + |
| 136 | + $ docker exec <container-name-or-id> reload |
| 137 | + |
| 138 | +The command will load the new configuration, compile it, and if compilation |
| 139 | +succeeds replace the old one with it. If compilation of the new configuration |
| 140 | +fails, the varnish daemon will continue to use the old configuration. |
| 141 | +Keep in mind that the only way to restore a previous configuration is to |
| 142 | +restore the configuration files and then reload them. |
| 143 | + |
| 144 | +### Support for stripping cookies for better caching |
| 145 | +By default, if any cookies are present, the cache is bypassed. This section describes |
| 146 | +new support for configuration of various cookie-based cache options. Configuration is |
| 147 | +enabled with the COOKIES environment variable. If set, additional code |
| 148 | +is executed that builds a cookie_config.vcl file containing additions to |
| 149 | +the generated default.vcl file. The following cookie options are currently supported. |
| 150 | + |
| 151 | +1. Whitelist of cookies - Allows stripping all but a small list of cookies |
| 152 | +2. (Future) Remove cookies for listed static file types, so caching works |
| 153 | + |
| 154 | +#### Whitelist of cookies |
| 155 | +With this option you provide a regular expression describing those cookies that should |
| 156 | +be passed through to the backend. All cookies not described by the expression will be |
| 157 | +stripped from the headers. Here is an example. |
| 158 | +``` |
| 159 | +COOKIES=true |
| 160 | +COOKIES_WHITELIST=(SESS[a-z0-9]+|SSESS[a-z0-9]+|NO_CACHE) |
| 161 | +``` |
| 162 | + |
| 163 | +### Upgrade |
| 164 | + |
| 165 | + $ docker pull eeacms/varnish |
| 166 | + |
| 167 | +## Supported environment variables ## |
| 168 | + |
| 169 | + |
| 170 | +As varnish has close to no purpose by itself, this image should be used |
| 171 | +in combination with others with [Docker Compose](https://docs.docker.com/compose/). |
| 172 | +The varnish daemon can be configured by modifying the following environment variables: |
| 173 | + |
| 174 | +* `CACHE_SIZE` Size of the RAM cache storage (default `2G`) |
| 175 | +* `ADDRESS_PORT` HTTP listen address and port (default `:6081`) |
| 176 | +* `ADMIN_PORT` HTTP admin address and port (e.g. `:6082`) |
| 177 | +* `BACKENDS` A list of `host[:port]` pairs separated by space |
| 178 | + (e.g. `BACKENDS="127.0.0.1 74.125.140.103:8080"`) |
| 179 | +* `BACKENDS_PORT` Default port to be used for backends (defalut `80`) |
| 180 | +* `BACKENDS_PROBE_ENABLED` Enable backend probe (default `True`) |
| 181 | +* `BACKENDS_PROBE_URL` Backend probe URL (default `/`) |
| 182 | +* `BACKENDS_PROBE_TIMEOUT` Backend probe timeout (defalut `1s`) |
| 183 | +* `BACKENDS_PROBE_INTERVAL` Backend probe interval (defalut `1s`) |
| 184 | +* `BACKENDS_PROBE_WINDOW` Backend probe window (defalut `3`) |
| 185 | +* `BACKENDS_PROBE_THRESHOLD` Backend probe threshold (defalut `2`) |
| 186 | +* `BACKENDS_SAINT_MODE` Register backends using [saintmode module](https://github.com/varnish/varnish-modules/blob/master/docs/saintmode.rst) |
| 187 | +* `BACKENDS_PROBE_REQUEST` Backend probe request header list (default empty) |
| 188 | +* `BACKENDS_PROBE_REQUEST_DELIMITER` Backend probe request headers delimiter (default `|`) |
| 189 | +* `BACKENDS_PURGE_LIST` Backend ip/ip range ';' separated list to use in the purge acl, defaults to `localhost;172.17.0.0/16;10.42.0.0/16` |
| 190 | +* `COOKIES` Enables cookie configuration |
| 191 | +* `COOKIES_WHITELIST` A regular expression describing cookies that are passed through, all others are stripped |
| 192 | +* `AUTOKILL_CRON` Has to be used with healtchecks enabled on varnish ports, it will kill the varnish cache process ( which exposes the ports ) keeping the container running, uses Linux Crontab format `[Minute] [hour] [Day_of_the_Month] [Month_of_the_Year] [Day_of_the_Week]`, UTC time |
| 193 | +* `VARNISH_SINGLE_CLUSTER` |
| 194 | +* `VARNISH_CLUSTER` |
| 195 | + |
| 196 | +## Copyright and license |
| 197 | + |
| 198 | +The Initial Owner of the Original Code is European Environment Agency (EEA). |
| 199 | +All Rights Reserved. |
| 200 | + |
| 201 | +The Original Code is free software; |
| 202 | +you can redistribute it and/or modify it under the terms of the GNU |
| 203 | +General Public License as published by the Free Software Foundation; |
| 204 | +either version 2 of the License, or (at your option) any later |
| 205 | +version. |
| 206 | + |
| 207 | + |
| 208 | +## Funding |
| 209 | + |
| 210 | +[European Environment Agency (EU)](http://eea.europa.eu) |
0 commit comments