From 6a3496f7230a6e25ed122dc286105a0dcab61d49 Mon Sep 17 00:00:00 2001
From: Guillaume Quintard <guillaume@varnish-software.com>
Date: Wed, 24 Mar 2021 17:20:08 -0700
Subject: [PATCH] [varnish] add extra configuration explanations

---
 varnish/content.md | 36 +++++++++++++++++++++++++++++++++---
 1 file changed, 33 insertions(+), 3 deletions(-)

diff --git a/varnish/content.md b/varnish/content.md
index 2b389fce2..765811471 100644
--- a/varnish/content.md
+++ b/varnish/content.md
@@ -23,13 +23,15 @@ backend default {
 Then run:
 
 ```console
-$ docker run --name my-running-varnish -v /path/to/default.vcl:/etc/varnish/default.vcl:ro --tmpfs /var/lib/varnish:exec -d %%IMAGE%%
+# we need both a configuration file at /etc/varnish/default.vcl
+# and our workdir to be mounted as tmpfs to avoid disk I/O
+$ docker run -v /path/to/default.vcl:/etc/varnish/default.vcl:ro --tmpfs /var/lib/varnish:exec %%IMAGE%%
 ```
 
 Alternatively, a simple `Dockerfile` can be used to generate a new image that includes the necessary `default.vcl` (which is a much cleaner solution than the bind mount above):
 
 ```dockerfile
-FROM %%IMAGE%%:6.2
+FROM %%IMAGE%%
 
 COPY default.vcl /etc/varnish/
 ```
@@ -37,7 +39,35 @@ COPY default.vcl /etc/varnish/
 Place this file in the same directory as your `default.vcl`, run `docker build -t my-varnish .`, then start your container:
 
 ```console
-$ docker run --name my-running-varnish --tmpfs /var/lib/varnish:exec -d my-varnish
+$ docker --tmpfs /var/lib/varnish:exec my-varnish
+```
+
+### Additional configuration
+
+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:
+
+```console
+$ docker run --tmpfs /var/lib/varnish:exec -e VARNISH_SIZE=2G %%IMAGE%%
+```
+
+Additionally, you can add arguments to `docker run` affter `%%IMAGE%%`, if the first one starts with a `-`, they will be appendend to the [default command](https://github.com/varnish/docker-varnish/blob/master/docker-varnish-entrypoint#L8):
+
+```console
+# extend the default keep period
+$ docker run --tmpfs /var/lib/varnish:exec -e VARNISH_SIZE=2G %%IMAGE%% -p default_keep=300
+```
+
+If your first argument after `%%IMAGE%%` doesn't start with `-`, it will be interpreted as a command to override the default one:
+
+```console
+# show the command-line options
+$ docker run %%IMAGE%% varnishd -?
+
+# list parameters usable with -p
+$ docker run %%IMAGE%% varnishd -x parameter
+
+# run the server with your own parameters (don't forget -F to not daemonize)
+$ docker run %%IMAGE%% varnishd -a :8080 -b 127.0.0.1:8181 -t 600 -p feature=+http2
 ```
 
 ### Exposing the port