20220206 documentation - master branch

Documentation updated to make it clear that the visibility of both a local and base image in `docker images` and Portainer depends on the version of docker-compose. Modern docker-compose only shows the local image so only a single "prune" is needed when a local image is rebuilt atop a newly-updated base image from DockerHub.

Affects documentation for Blynk Server, Mosquitto, NextCloud, Node-RED, Telegraf and Zigbee2MQTT. Prometheus documentation already updated in [PR487](#487).

Signed-off-by: Phill Kelley <[email protected]>

Author: Paraphraser

docs/Containers/Blynk_server.md

@@ -115,7 +115,7 @@ The remaining instructions in the *Dockerfile* customise the ***base image*** to
 
 The ***local image*** is instantiated to become your running container.
 
-When you run the `docker images` command after Blynk Server has been built, you will see two rows that are relevant:
+When you run the `docker images` command after Blynk Server has been built, you *may* see two rows that are relevant:
 
 ```bash
 $ docker images
@@ -127,7 +127,9 @@ ubuntu                  latest   897590a6c564   7 days ago      49.8MB
 * `ubuntu ` is the ***base image***; and
 * `iotstack_blynk_server ` is the ***local image***.
 
-You will see the same pattern in *Portainer*, which reports the ***base image*** as "unused". You should not remove the ***base*** image, even though it appears to be unused.
+You *may* see the same pattern in *Portainer*, which reports the ***base image*** as "unused". You should not remove the ***base*** image, even though it appears to be unused.
+
+> Whether you see one or two rows depends on the version of `docker-compose` you are using and how your version of `docker-compose` builds local images.
 
 ## <a name="logging"> Logging </a>
 
@@ -216,6 +218,8 @@ At the time of writing, version 0.41.16 was the most up-to-date. Suppose that ve
 		$ docker system prune -f
 		```
 
+		The second `prune` will only be needed if there is an old *base image* and that, in turn, depends on the version of `docker-compose` you are using and how your version of `docker-compose` builds local images.
+
 ## <a name="usingBlynkServer"> Using Blynk Server </a>
 
 See the [References](#references) for documentation links.

docs/Containers/Mosquitto.md

@@ -128,7 +128,7 @@ The remaining instructions in the *Dockerfile* customise the *base image* to pro
 
 The *local image* is instantiated to become your running container.
 
-When you run the `docker images` command after Mosquitto has been built, you will see two rows for Mosquitto:
+When you run the `docker images` command after Mosquitto has been built, you *may* see two rows for Mosquitto:
 
 ```bash
 $ docker images
@@ -140,7 +140,9 @@ eclipse-mosquitto               latest      46ad1893f049   4 weeks ago    8.31MB
 * `eclipse-mosquitto` is the *base image*; and
 * `iotstack_mosquitto` is the *local image*.
 
-You will see the same pattern in Portainer, which reports the *base image* as "unused". You should not remove the *base* image, even though it appears to be unused.
+You *may* see the same pattern in Portainer, which reports the *base image* as "unused". You should not remove the *base* image, even though it appears to be unused.
+
+> Whether you see one or two rows depends on the version of `docker-compose` you are using and how your version of `docker-compose` builds local images.
 
 ### <a name="migration"> Migration considerations </a>
 
@@ -632,7 +634,7 @@ Breaking it down into parts:
 
 Your existing Mosquitto container continues to run while the rebuild proceeds. Once the freshly-built *local image* is ready, the `up` tells `docker-compose` to do a new-for-old swap. There is barely any downtime for your MQTT broker service.
 
-The `prune` is the simplest way of cleaning up. The first call removes the old *local image*. The second call cleans up the old *base image*.
+The `prune` is the simplest way of cleaning up. The first call removes the old *local image*. The second call cleans up the old *base image*. Whether an old *base image* exists depends on the version of `docker-compose` you are using and how your version of `docker-compose` builds local images.
 
 ### <a name="versionPinning"> Mosquitto version pinning </a>
 

docs/Containers/NextCloud.md

@@ -288,7 +288,7 @@ $ docker system prune
 $ docker system prune
 ```
 
-The first "prune" removes the old *local* image, the second removes the old *base* image.
+The first "prune" removes the old *local* image, the second removes the old *base* image. Whether an old *base image* exists depends on the version of `docker-compose` you are using and how your version of `docker-compose` builds local images.
 
 ## <a name="backups"> Backups </a>
 

docs/Containers/Node-RED.md

@@ -115,7 +115,7 @@ Notes:
 
 	> Acknowledgement: Successful installation of the SQLite node is thanks to @fragolinux.
 
-When you run the `docker images` command after Node-RED has been built, you will see two rows for Node-RED:
+When you run the `docker images` command after Node-RED has been built, you *may* see two rows for Node-RED:
 
 ```bash
 $ docker images
@@ -127,12 +127,14 @@ nodered/node-red         latest              deb99584fa75        5 days ago
 * `nodered/node-red` is the *base image*; and
 * `iotstack_nodered` is the *local image*. The *local* image is the one that is instantiated to become the running container.
 
-You will see the same pattern in Portainer, which reports the *base image* as "unused":
+You *may* see the same pattern in Portainer, which reports the *base image* as "unused":
 
 ![nodered-portainer-unused-image](./images/nodered-portainer-unused-image.png)
 
 You should not remove the *base* image, even though it appears to be unused.
 
+> Whether you see one or two rows depends on the version of `docker-compose` you are using and how your version of `docker-compose` builds local images.
+
 ## <a name="securingNodeRed"> Securing Node-RED </a>
 
 ### <a name="nodeRedEncryptionKey"> Setting an encryption key for your credentials </a>
@@ -858,7 +860,8 @@ Breaking it down into parts:
 
 Your existing Node-RED container continues to run while the rebuild proceeds. Once the freshly-built *local image* is ready, the `up` tells `docker-compose` to do a new-for-old swap. There is barely any downtime for your Node-RED service.
 
-The `prune` is the simplest way of cleaning up old images. Sometimes you need to run this twice, the first time to clean up the old local image, the second time for the old base image.
+The `prune` is the simplest way of cleaning up old images. Sometimes you need to run this twice, the first time to clean up the old local image, the second time for the old base image. Whether an old base image exists depends on the version of `docker-compose` you are using and how your version of `docker-compose` builds local images.
+
 
 ## <a name="customisingNodeRed"> Customising Node-RED </a>
 

docs/Containers/Telegraf.md

@@ -118,7 +118,7 @@ The remaining instructions in the *Dockerfile* customise the ***base image*** to
 
 The ***local image*** is instantiated to become your running container.
 
-When you run the `docker images` command after Telegraf has been built, you will see two rows for Telegraf:
+When you run the `docker images` command after Telegraf has been built, you *may* see two rows for Telegraf:
 
 ```bash
 $ docker images
@@ -130,7 +130,9 @@ telegraf            latest   a721ac170fad   3 days ago    273MB
 * `telegraf ` is the ***base image***; and
 * `iotstack_telegraf ` is the ***local image***.
 
-You will see the same pattern in *Portainer*, which reports the ***base image*** as "unused". You should not remove the ***base*** image, even though it appears to be unused.
+You *may* see the same pattern in *Portainer*, which reports the ***base image*** as "unused". You should not remove the ***base*** image, even though it appears to be unused.
+
+> Whether you see one or two rows depends on the version of `docker-compose` you are using and how your version of `docker-compose` builds local images.
 
 ### <a name="migration"> Migration considerations </a>
 
@@ -331,7 +333,7 @@ Breaking it down into parts:
 
 Your existing Telegraf container continues to run while the rebuild proceeds. Once the freshly-built ***local image*** is ready, the `up` tells `docker-compose` to do a new-for-old swap. There is barely any downtime for your service.
 
-The `prune` is the simplest way of cleaning up. The first call removes the old ***local image***. The second call cleans up the old ***base image***.
+The `prune` is the simplest way of cleaning up. The first call removes the old ***local image***. The second call cleans up the old ***base image***. Whether an old ***base image*** exists depends on the version of `docker-compose` you are using and how your version of `docker-compose` builds local images.
 
 ### <a name="versionPinning"> Telegraf version pinning </a>
 

docs/Containers/Zigbee2MQTT.md

@@ -259,4 +259,4 @@ $ docker system prune
 
 Note:
 
-* Sometimes it is necessary to repeat the `docker system prune` command.
+* Sometimes it is necessary to repeat the `docker system prune` command but it depends on the version of `docker-compose` you are using and how your version of `docker-compose` builds local images.