You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: varnish/README.md
+77-62Lines changed: 77 additions & 62 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -61,37 +61,51 @@ Varnish is an HTTP accelerator designed for content-heavy dynamic web sites as w
61
61
62
62
# How to use this image.
63
63
64
+
```console
65
+
$ docker run -p 8080:80 --ulimit memlock=-1:-1 --tmpfs /var/lib/varnish/varnishd:exec varnish
66
+
```
67
+
68
+
You can then visit [http://localhost:8080](http://localhost:8080) with your browser and be greeted by the default landing page.
69
+
70
+
**Note:** while the `--ulimit` and `--tmpfs` options aren't necessary, they are greatly recommended. More details are available at the end of this page.
71
+
64
72
## Basic usage
65
73
66
-
### Using `VARNISH_BACKEND_HOST` and `VARNISH_BACKEND_PORT`
74
+
### Simple cache
67
75
68
-
You just need to know where your backend (the server that Varnish will accelerate) is:
76
+
The default Varnish configuration will read the `VARNISH_BACKEND_HOST` environment variable which should be an HTTP or HTTPS URL, for example:
69
77
70
78
```console
71
-
# we define VARNISH_BACKEND_HOST/VARNISH_BACKEND_PORT
72
-
# our workdir has to be mounted as tmpfs to avoid disk I/O,
73
-
# and we'll use port 8080 to talk to our container (internally listening on 80)
From there, you can visit `localhost:8080` in your browser and see the example.com homepage.
87
+
By default, Varnish is extremely careful regarding what it can and cannot cache by looking at the [client request](https://www.varnish-software.com/developers/tutorials/varnish-builtin-vcl/#1-vcl_recv) and at the [backend response](https://www.varnish-software.com/developers/tutorials/varnish-builtin-vcl/#11-vcl_backend_response).
82
88
83
-
### Using a VCL file
89
+
Notably, Varnish will not cache if:
90
+
91
+
- the request is not a `GET` or `HEAD`
92
+
- the request contains an `Authorization` or `Cookie` header
93
+
- the response status is not cacheable (i.e., not a 2xx or 4xx response)
94
+
- the response contains a `Set-Cookie` header
95
+
- the response contains headers indicating it is uncacheable
96
+
97
+
These rules can, of course, be overridden by providing your own `VCL` file, as explained in the next section.
98
+
99
+
### Custom caching logic
84
100
85
101
If you already have a VCL file, you can directly mount it as `/etc/varnish/default.vcl`:
86
102
87
103
```console
88
-
# we need the configuration file at /etc/varnish/default.vcl,
89
-
# our workdir has to be mounted as tmpfs to avoid disk I/O,
90
-
# and we'll use port 8080 to talk to our container (internally listening on 80)
The images all ship with [varnishreload](https://github.com/varnishcache/pkg-varnish-cache/blob/master/systemd/varnishreload#L42) which allows you to easily update the running configuration without restarting the container (and therefore losing your cache). At its most basic, you just need this:
132
+
The images all ship with [varnishreload](https://github.com/varnish/all-packager/blob/809d3c098d1cb84d1b85e18573121a3a3720c898/varnish/systemd/varnishreload#L48-L82) which allows you to easily update the running configuration without restarting the container (and therefore losing your cache). At its most basic, you just need this:
Note that `varnishreload` also supports reloading other files (it doesn't have to be `default.vcl`), labels (`l`), and garbage collection of old labeles (`-m`) among others. To know more, run
141
+
Note that `varnishreload` also supports reloading other files (it doesn't have to be `default.vcl`), labels (`-l`), and garbage collection of old labels (`-m`), among others. To learn more, run
142
+
143
+
```console
144
+
$ docker run --rm varnish varnishreload -h
145
+
```
146
+
147
+
## File server
148
+
149
+
Using the included [vmod-fileserver](https://github.com/varnish-rs/vmod-fileserver), Varnish can be used as a file server. Just mount the directory you want to expose into the `/var/www/html` directory and set the `VARNISH_FILESERVER` variable to `true`:
124
150
125
151
```console
126
-
docker run varnish varnishreload -h
152
+
$ docker run \
153
+
--ulimit memlock=-1:-1 \
154
+
--tmpfs /var/lib/varnish/varnishd:exec \
155
+
-p 8080:80 \
156
+
-v /dir/to/expose:/var/www/html:ro \
157
+
-e VARNISH_FILESERVER=true \
158
+
varnish
127
159
```
128
160
129
-
## Additional configuration
161
+
**Note:** Varnish will reply with an empty 200 when trying to access folders instead of individual files.
162
+
163
+
## Environment variables
164
+
165
+
### Backend address (`VARNISH_BACKEND_HOST`)
166
+
167
+
Set the backend address and protocol as explained above. This only works with the provided `VCL`, i.e. if you don't mount an `/etc/varnish/default.vcl` file, and if you don't set `VARNISH_VCL_FILE`
168
+
169
+
### File server mode (`VARNISH_FILESERVER`)
170
+
171
+
Also only valid with the default `VCL`. If `VARNISH_BACKEND_HOST` is unset and `VARNISH_FILESERVER` is set, Varnish will act as a server, using `/var/www/html` as its source.
130
172
131
-
### Cache size (VARNISH_SIZE)
173
+
### Cache size (`VARNISH_SIZE`)
132
174
133
175
By default, the containers will use a cache size of 100MB, which is usually a bit too small, but you can quickly set it through the `VARNISH_SIZE` environment variable:
134
176
135
177
```console
136
178
$ docker run --tmpfs /var/lib/varnish/varnishd:exec -p 8080:80 -e VARNISH_SIZE=2G varnish
Varnish will listen to HTTP traffic on port `80`, and this can be overridden by setting the environment variable `VARNISH_HTTP_PORT`. Similarly, the variable `VARNISH_PROXY_PORT` (defaulting to `8443`) dictate the listening port for the [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) used notably to interact with [hitch](https://hub.docker.com/_/hitch) (which, coincidentally, uses `8443` as a default too!).
183
+
Varnish will listen to HTTP traffic on port `80`, and this can be overridden by setting the environment variable `VARNISH_HTTP_PORT`. Similarly, the variable `VARNISH_PROXY_PORT` (defaulting to `8443`) dictates the listening port for the [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) used notably to interact with [hitch](https://hub.docker.com/_/hitch) (which, coincidentally, uses `8443` as a default too!).
142
184
143
185
```console
144
-
# instruct varnish to listening to port 7777 instead of 80
186
+
# instruct varnish to listen on port 7777 instead of 80
145
187
$ docker run --tmpfs /var/lib/varnish/varnishd:exec -p 8080:7777 -e VARNISH_HTTP_PORT=7777 varnish
146
188
```
147
189
148
-
### VCL file path
190
+
### VCL file (`VARNISH_VCL_FILE`)
149
191
150
192
The default Varnish configuration file is `/etc/varnish/default.vcl`, but this can be overridden with the `VARNISH_VCL_FILE` environment variable. This is useful if you want a single image that can be deployed with different configurations baked in it.
151
193
152
194
### Extra arguments
153
195
154
-
Additionally, you can add arguments to `docker run` after `varnish`, if the first argument starts with a `-`, the whole list will be appendend to the [default command](https://github.com/varnish/docker-varnish/blob/master/fresh/debian/scripts/docker-varnish-entrypoint):
196
+
Additionally, you can add arguments to `docker run` after `varnish`, if the first argument starts with a `-`, the whole list will be appended to the [default command](https://github.com/varnish/docker-varnish/blob/master/fresh/debian/scripts/docker-varnish-entrypoint):
$ docker run varnish varnishd -F -a :8080 -b 127.0.0.1:8181 -t 600 -p feature=+http2
172
218
```
173
219
174
-
## vmods (since 7.1)
175
-
176
-
As mentioned above, you can use [vmod_dynamic](https://github.com/nigoroll/libvmod-dynamic) for backend resolution. The [varnish-modules](https://github.com/varnish/varnish-modules) collection is also included in the image. All the documentation regarding usage and syntax can be found in the [src/](https://github.com/varnish/varnish-modules/tree/master/src) directory of the repository.
220
+
This can notably be used to extract logs using [varnishncsa or varnishlog](https://www.varnish-software.com/developers/tutorials/vsl-cheatsheet/), running `varnishstat -1` to extract metrics, and of course reloading the `VCL` with `varnishreload`.
177
221
178
-
On top of this, images include [install-vmod](https://github.com/varnish/toolbox/tree/master/install-vmod), a helper script to quickly download, compile and install vmods while creating your own images. Note that images set the `ENV` variable `VMOD_DEPS` to ease the task further.
222
+
## Vmods
179
223
180
-
### Debian
224
+
The docker image is built with a collection of "`VCL` modules" or "vmods" that extend Varnish capability. We've already covered `vmod-fileserver` (file backend) and `vmod-reqwest` (dynamic backends), but more are available and can be used in your custom `VCL` with `import <vmod_name>`. Please refer to the documentation of each vmod for more information.
181
225
182
-
```dockerfile
183
-
FROM varnish:7.1
184
-
185
-
# set the user to root, and install build dependencies
Varnish uses [memory-mapped files](https://docs.varnish-software.com/varnish-enterprise/installation/#the-shared-memory-log) to log and store metrics for performance reasons. Those files are constantly written to, and to get the most out of your system, you should:
0 commit comments