Merge pull request #772 from nginx-proxy/doc-volume

Update volume-related docs and examples

README.md

@@ -51,9 +51,9 @@ $ docker run --detach \
     --name nginx-proxy \
     --publish 80:80 \
     --publish 443:443 \
-    --volume /etc/nginx/certs \
-    --volume /etc/nginx/vhost.d \
-    --volume /usr/share/nginx/html \
+    --volume certs:/etc/nginx/certs \
+    --volume vhost:/etc/nginx/vhost.d \
+    --volume html:/usr/share/nginx/html \
     --volume /var/run/docker.sock:/tmp/docker.sock:ro \
     jwilder/nginx-proxy
 ```
@@ -69,7 +69,7 @@ $ docker run --detach \
     --name nginx-proxy-letsencrypt \
     --volumes-from nginx-proxy \
     --volume /var/run/docker.sock:/var/run/docker.sock:ro \
-    --volume /etc/acme.sh \
+    --volume acme:/etc/acme.sh \
     --env "DEFAULT_EMAIL=mail@yourdomain.tld" \
     jrcs/letsencrypt-nginx-proxy-companion
 ```

docs/Advanced-usage.md

@@ -28,10 +28,10 @@ $ docker run --detach \
     --publish 80:80 \
     --publish 443:443 \
     --name nginx \
-    --volume /etc/nginx/conf.d  \
-    --volume /etc/nginx/vhost.d \
-    --volume /usr/share/nginx/html \
-    --volume /etc/nginx/certs \
+    --volume conf:/etc/nginx/conf.d  \
+    --volume vhost:/etc/nginx/vhost.d \
+    --volume html:/usr/share/nginx/html \
+    --volume certs:/etc/nginx/certs \
     nginx
 ```
 
@@ -61,7 +61,7 @@ $ docker run --detach \
     --name nginx-proxy-letsencrypt \
     --volumes-from nginx-proxy \
     --volume /var/run/docker.sock:/var/run/docker.sock:ro \
-    --volume /etc/acme.sh \
+    --volume acme:/etc/acme.sh \
     --env "NGINX_DOCKER_GEN_CONTAINER=nginx-proxy-gen" \
     --env "DEFAULT_EMAIL=mail@yourdomain.tld" \
     jrcs/letsencrypt-nginx-proxy-companion

docs/Basic-usage.md

@@ -21,9 +21,9 @@ $ docker run --detach \
     --name nginx-proxy \
     --publish 80:80 \
     --publish 443:443 \
-    --volume /etc/nginx/certs \
-    --volume /etc/nginx/vhost.d \
-    --volume /usr/share/nginx/html \
+    --volume certs:/etc/nginx/certs \
+    --volume vhost:/etc/nginx/vhost.d \
+    --volume html:/usr/share/nginx/html \
     --volume /var/run/docker.sock:/tmp/docker.sock:ro \
     jwilder/nginx-proxy
 ```
@@ -39,7 +39,7 @@ $ docker run --detach \
     --name nginx-proxy-letsencrypt \
     --volumes-from nginx-proxy \
     --volume /var/run/docker.sock:/var/run/docker.sock:ro \
-    --volume /etc/acme.sh \
+    --volume acme:/etc/acme.sh \
     --env "DEFAULT_EMAIL=mail@yourdomain.tld" \
     jrcs/letsencrypt-nginx-proxy-companion
 ```

docs/Container-configuration.md

@@ -10,8 +10,9 @@ For example
 $ docker run --detach \
     --name nginx-proxy-letsencrypt \
     --volumes-from nginx-proxy \
-    --volume /path/to/certs:/etc/nginx/certs:rw \
     --volume /var/run/docker.sock:/var/run/docker.sock:ro \
+    --volume certs:/etc/nginx/certs:rw \
+    --volume acme:/etc/acme.sh \
     --env "ACME_CA_URI=https://acme-staging-v02.api.letsencrypt.org/directory" \
     jrcs/letsencrypt-nginx-proxy-companion
 ```

docs/Persistent-data.md

@@ -1,31 +1,8 @@
 ## Persistent data
 
-### Anonymous volumes
-
-When you follow instructions from Basic usage or Advanced usage, Docker will automatically create **anonymous volumes** (volumes with a random name) for every `--volume` / `-v` argument passed:
-
-```shell
-$ docker run -d \
-    --name nginx-proxy \
-    -p 80:80 \
-    -p 443:443 \
-    -v /etc/nginx/certs \
-    -v /etc/nginx/vhost.d \
-    -v /usr/share/nginx/html \
-    -v /var/run/docker.sock:/tmp/docker.sock:ro \
-    jwilder/nginx-proxy
-
-$ docker volume ls
-DRIVER              VOLUME NAME
-local               287be3abd610e5566500d719ceb8b952952f12c9324ef02d05785d4ee9737ae9
-local               6530b1b40cf89efb71aa7fd19bddec927fa2bcae59b04b9c1c850af72ffe0123
-local               f260f71fefadcdfc311d285d69151f2312915174d3fb1fab89949ec5ec871a54
-local               f2cd94ca48904dc9cfc840ce4b265a04831c580d525253d7a0e5aac4d1dca340
-```
-
 ### Named volumes (recommended)
 
-Using **named volumes** instead make managing volumes easier:
+When you follow instructions from Basic usage or Advanced usage, Docker will automatically create **named volumes** for every `--volume` / `-v` argument passed. Named volume will make it easy for you to mount the same persisted data even if you delete then re-create the container:
 
 ```shell
 $ docker run -d \
@@ -45,6 +22,28 @@ local               vhost
 local               html
 ```
 
+### Anonymous volumes (not recommended)
+
+If you don't prefix your volumes with a name, Docker will instead create **anonymous volumes** (volumes with a random name). Those volume persist after the container is deleted but aren't automatically re-mounted when you re-create the container. Their usage is **not recommended** as they don't provide any advantages over named volumes and make keeping tracks of what volume store which data way harder.
+
+```shell
+$ docker run -d \
+    --name nginx-proxy \
+    -p 80:80 \
+    -p 443:443 \
+    -v /etc/nginx/certs \
+    -v /etc/nginx/vhost.d \
+    -v /usr/share/nginx/html \
+    -v /var/run/docker.sock:/tmp/docker.sock:ro \
+    jwilder/nginx-proxy
+
+$ docker volume ls
+DRIVER              VOLUME NAME
+local               287be3abd610e5566500d719ceb8b952952f12c9324ef02d05785d4ee9737ae9
+local               6530b1b40cf89efb71aa7fd19bddec927fa2bcae59b04b9c1c850af72ffe0123
+local               f260f71fefadcdfc311d285d69151f2312915174d3fb1fab89949ec5ec871a54
+```
+
 ### Host volumes
 
 Alternatively, you might want to store the certificates on a local folder rather than letting Docker create and manage a volume for them. This is easily achieved by using a **host volume** (binding an absolute path on your host to the `/ect/nginx/certs` folder on your containers):

docs/Standalone-certificates.md

@@ -7,10 +7,10 @@ $ docker run --detach \
     --name nginx-proxy \
     --publish 80:80 \
     --publish 443:443 \
-    --volume /etc/nginx/certs \
-    --volume /etc/nginx/vhost.d \
-    --volume /etc/nginx/conf.d \
-    --volume /usr/share/nginx/html \
+    --volume certs:/etc/nginx/certs \
+    --volume vhost:/etc/nginx/vhost.d \
+    --volume conf:/etc/nginx/conf.d \
+    --volume html:/usr/share/nginx/html \
     --volume /var/run/docker.sock:/tmp/docker.sock:ro \
     jwilder/nginx-proxy
 ```
@@ -19,6 +19,7 @@ $ docker run --detach \
     --name nginx-proxy-letsencrypt \
     --volumes-from nginx-proxy \
     --volume /var/run/docker.sock:/var/run/docker.sock:ro \
+    --volume acme:/etc/acme.sh \
     --volume /path/to/your/config_file:/app/letsencrypt_user_data:ro \
     jrcs/letsencrypt-nginx-proxy-companion
 ```