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/content.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
@@ -8,37 +8,51 @@ Varnish is an HTTP accelerator designed for content-heavy dynamic web sites as w
8
8
9
9
# How to use this image.
10
10
11
+
```console
12
+
$ docker run -p 8080:80 --ulimit memlock=-1:-1 --tmpfs /var/lib/varnish/varnishd:exec %%IMAGE%%
13
+
```
14
+
15
+
You can then visit [http://localhost:8080](http://localhost:8080) with your browser and be greeted by the default landing page.
16
+
17
+
**Note:** while the `--ulimit` and `--tmpfs` options aren't necessary, they are greatly recommended. More details are available at the end of this page.
18
+
11
19
## Basic usage
12
20
13
-
### Using `VARNISH_BACKEND_HOST` and `VARNISH_BACKEND_PORT`
21
+
### Simple cache
14
22
15
-
You just need to know where your backend (the server that Varnish will accelerate) is:
23
+
The default Varnish configuration will read the `VARNISH_BACKEND_HOST` environment variable which should be an HTTP or HTTPS URL, for example:
16
24
17
25
```console
18
-
# we define VARNISH_BACKEND_HOST/VARNISH_BACKEND_PORT
19
-
# our workdir has to be mounted as tmpfs to avoid disk I/O,
20
-
# 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.
34
+
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).
29
35
30
-
### Using a VCL file
36
+
Notably, Varnish will not cache if:
37
+
38
+
- the request is not a `GET` or `HEAD`
39
+
- the request contains an `Authorization` or `Cookie` header
40
+
- the response status is not cacheable (i.e., not a 2xx or 4xx response)
41
+
- the response contains a `Set-Cookie` header
42
+
- the response contains headers indicating it is uncacheable
43
+
44
+
These rules can, of course, be overridden by providing your own `VCL` file, as explained in the next section.
45
+
46
+
### Custom caching logic
31
47
32
48
If you already have a VCL file, you can directly mount it as `/etc/varnish/default.vcl`:
33
49
34
50
```console
35
-
# we need the configuration file at /etc/varnish/default.vcl,
36
-
# our workdir has to be mounted as tmpfs to avoid disk I/O,
37
-
# 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:
79
+
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
88
+
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
89
+
90
+
```console
91
+
$ docker run --rm %%IMAGE%% varnishreload -h
92
+
```
93
+
94
+
## File server
95
+
96
+
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`:
71
97
72
98
```console
73
-
docker run varnish varnishreload -h
99
+
$ docker run \
100
+
--ulimit memlock=-1:-1 \
101
+
--tmpfs /var/lib/varnish/varnishd:exec \
102
+
-p 8080:80 \
103
+
-v /dir/to/expose:/var/www/html:ro \
104
+
-e VARNISH_FILESERVER=true \
105
+
%%IMAGE%%
74
106
```
75
107
76
-
## Additional configuration
108
+
**Note:** Varnish will reply with an empty 200 when trying to access folders instead of individual files.
109
+
110
+
## Environment variables
111
+
112
+
### Backend address (`VARNISH_BACKEND_HOST`)
113
+
114
+
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`
115
+
116
+
### File server mode (`VARNISH_FILESERVER`)
117
+
118
+
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.
77
119
78
-
### Cache size (VARNISH_SIZE)
120
+
### Cache size (`VARNISH_SIZE`)
79
121
80
122
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:
81
123
82
124
```console
83
125
$ docker run --tmpfs /var/lib/varnish/varnishd:exec -p 8080:80 -e VARNISH_SIZE=2G %%IMAGE%%
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!).
130
+
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!).
89
131
90
132
```console
91
-
# instruct varnish to listening to port 7777 instead of 80
133
+
# instruct varnish to listen on port 7777 instead of 80
92
134
$ docker run --tmpfs /var/lib/varnish/varnishd:exec -p 8080:7777 -e VARNISH_HTTP_PORT=7777 %%IMAGE%%
93
135
```
94
136
95
-
### VCL file path
137
+
### VCL file (`VARNISH_VCL_FILE`)
96
138
97
139
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.
98
140
99
141
### Extra arguments
100
142
101
-
Additionally, you can add arguments to `docker run` after `%%IMAGE%%`, 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):
143
+
Additionally, you can add arguments to `docker run` after `%%IMAGE%%`, 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 %%IMAGE%% varnishd -F -a :8080 -b 127.0.0.1:8181 -t 600 -p feature=+http2
119
165
```
120
166
121
-
## vmods (since 7.1)
122
-
123
-
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.
167
+
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`.
124
168
125
-
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.
169
+
## Vmods
126
170
127
-
### Debian
171
+
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.
128
172
129
-
```dockerfile
130
-
FROM %%IMAGE%%:7.1
131
-
132
-
# 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