Merge pull request #562 from ukkopahis/doc-improvements

Doc improvements

Author: Slyke

README.md

@@ -15,68 +15,11 @@ See [Getting Started](https://sensorsiot.github.io/IOTstack/Getting-Started) in
 
 ### significant change to networking
 
-Networking under both *new menu* (master branch) and *old menu* (old-menu branch) has undergone a significant change. This will not affect new users of IOTstack (who will adopt it automatically). Neither will it affect existing users who do not use the menu to maintain their stacks (see [adopting networking changes by hand](#networkHandEdit) below).
- 
-Users who *do* use the menu to maintain their stacks will also be unaffected *until the next menu run*, at which point it will be prudent to down your stack entirely and re-select all your containers. Downing the stack causes Docker to remove all associated networks as well as the containers.
+After 2022-01-18 the menu has changed to use Docker networks differently. Users from before this need to do [migration](https://sensorsiot.github.io/IOTstack/Updates/migration-network-change/) in order to add new services. In essence, just re-select all your services using the menu. If not done, docker-compose will give you an error like:
 
-These changes mean that networking is **identical** under both *old* and *new* menus. To summarise the changes:
-
-1. Only two internal networks are defined – as follows:
-
-	* "default" which adopts the name `iotstack_default` at runtime.
-	* "nextcloud" which adopts the name `iotstack_nextcloud` at runtime.
-	
-	If you are using docker-compose v2.0.0 or later then the `iotstack_nextcloud` network will only be instantiated if you select NextCloud as one of your services. Earlier versions of docker-compose instantiate all networks even if no service uses them (which is why you get those warnings at "up" time).
-
-2. The only service definitions which now have `networks:` directives are:
-
-	* NextCloud: joins the "default" and "nextcloud" networks; and
-	* NextCloud_DB: joins the "nextcloud" network.
-	
-	All other containers will join the "default" network, automatically, without needing any `networks:` directives.
-
-#### <a name="networkHandEdit"> adopting networking changes by hand </a>
-
-If you maintain your `docker-compose.yml` by hand, you can adopt the networking changes by doing the following:
-
-1. Take your stack down. This causes Docker to remove any existing networks. 
-2. Remove **all** `networks:` directives wherever they appear in your `docker-compose.yml`. That includes: 
-
-	* the `networks:` directives in all service definitions; and
-	* the `networks:` specifications at the end of the file.
-
-3. Append the contents of the following file to your `docker-compose.yml`:
-
-	```
-	~/IOTstack/.templates/env.yml
-	```
-
-	For example:
-	
-	```
-	$ cat ~/IOTstack/.templates/env.yml >>~/IOTstack/docker-compose.yml
-	```
-	
-	The `env.yml` file is the same for both *old-menu* and *master* branches.
-
-4. If you run the NextCloud service then:
-
-	* Add these lines to the NextCloud service definition:
-
-		```
-		networks:
-		  - default
-		  - nextcloud
-		```
-
-	* Add these lines to the NextCloud_DB service definition:
-
-		```
-		networks:
-		  - nextcloud
-		```
-
-5. Bring up your stack.	
+```
+ERROR: Service "influxdb" uses an undefined network "iotstack_nw"
+```
 
 ### contributions
 

docs/Basic_setup/index.md

@@ -116,9 +116,8 @@ Please don't read these assumptions as saying that IOTstack will not run on othe
 
 ### scripted
 
-If you prefer to automate your installations using scripts, see:
-
-* [Installing Docker for IOTstack](https://gist.github.com/Paraphraser/d119ae81f9e60a94e1209986d8c9e42f#scripting-iotstack-installations).
+If you prefer to automate your installations using scripts, see
+[PiBuilder](https://github.com/Paraphraser/PiBuilder).
 
 ## Required system patches
 
@@ -130,7 +129,6 @@ Run the following commands:
 
 ``` console
 $ sudo bash -c '[ $(egrep -c "^allowinterfaces eth\*,wlan\*" /etc/dhcpcd.conf) -eq 0 ] && echo "allowinterfaces eth*,wlan*" >> /etc/dhcpcd.conf'
-$ sudo reboot
 ```
 
 See [Issue 219](https://github.com/SensorsIot/IOTstack/issues/219) and [Issue 253](https://github.com/SensorsIot/IOTstack/issues/253) for more information.
@@ -139,32 +137,32 @@ See [Issue 219](https://github.com/SensorsIot/IOTstack/issues/219) and [Issue 25
 
 This patch is **ONLY** for Raspbian Buster. Do **NOT** install this patch if you are running Raspbian Bullseye.
 
-#### step 1: check your OS release
+1.  check your OS release
 
-Run the following command:
+    Run the following command:
 
-``` console
-$ grep "PRETTY_NAME" /etc/os-release
-PRETTY_NAME="Raspbian GNU/Linux 10 (buster)"
-```
+    ``` console
+    $ grep "PRETTY_NAME" /etc/os-release
+    PRETTY_NAME="Raspbian GNU/Linux 10 (buster)"
+    ```
 
-If you see the word "buster", proceed to step 2. Otherwise, skip this patch.
+    If you see the word "buster", proceed to step 2. Otherwise, skip this patch.
 
-#### step 2: if you are indeed running "buster"
+2.  if you are indeed running "buster"
 
-Without this patch on Buster, Docker images will fail if:
+    Without this patch on Buster, Docker images will fail if:
 
-* the image is based on Alpine and the image's maintainer updates to [Alpine 3.13](https://wiki.alpinelinux.org/wiki/Release_Notes_for_Alpine_3.13.0#time64_requirement); and/or
-* an image's maintainer updates to a library that depends on 64-bit values for *Unix epoch time* (the so-called Y2038 problem).
+    * the image is based on Alpine and the image's maintainer updates to [Alpine 3.13](https://wiki.alpinelinux.org/wiki/Release_Notes_for_Alpine_3.13.0#time64_requirement); and/or
+    * an image's maintainer updates to a library that depends on 64-bit values for *Unix epoch time* (the so-called Y2038 problem).
 
-To install the patch:
+    To install the patch:
 
-``` console
-$ sudo apt-key adv --keyserver hkps://keyserver.ubuntu.com:443 --recv-keys 04EE7237B7D453EC 648ACFD622F3D138
-$ echo "deb http://httpredir.debian.org/debian buster-backports main contrib non-free" | sudo tee -a "/etc/apt/sources.list.d/debian-backports.list"
-$ sudo apt update
-$ sudo apt install libseccomp2 -t buster-backports
-```
+    ``` console
+    $ sudo apt-key adv --keyserver hkps://keyserver.ubuntu.com:443 --recv-keys 04EE7237B7D453EC 648ACFD622F3D138
+    $ echo "deb http://httpredir.debian.org/debian buster-backports main contrib non-free" | sudo tee -a "/etc/apt/sources.list.d/debian-backports.list"
+    $ sudo apt update
+    $ sudo apt install libseccomp2 -t buster-backports
+    ```
 
 ### patch 3 - kernel control groups
 
@@ -173,10 +171,11 @@ usage. This makes commands like `docker stats` fully work. Also needed for full
 monitoring of docker resource usage by the telegraf container.
 
 Enable by running (takes effect after reboot):
-```
-echo $(cat /boot/cmdline.txt) cgroup_memory=1 cgroup_enable=memory | sudo tee /boot/cmdline.txt
-```
 
+``` console
+$ echo $(cat /boot/cmdline.txt) cgroup_memory=1 cgroup_enable=memory | sudo tee /boot/cmdline.txt
+$ sudo reboot
+```
 
 ## the IOTstack menu
 
@@ -501,33 +500,15 @@ You read this as two paths, separated by a colon. The:
 * external path is `./volumes/nodered/data`
 * internal path is `/data`
 
-In this context, the leading "." means "the folder containing `docker-compose.yml`", so the external path is actually:
+In this context, the leading "." means "the folder containing`docker-compose.yml`", so the external path is actually:
 
 * `~/IOTstack/volumes/nodered/data`
 
-If a process running **inside** the container modifies any file or folder within:
-
-```
-/data
-```
-
-the change is mirrored **outside** the container at the same relative path within:
-
-```
-~/IOTstack/volumes/nodered/data
-```
-
-The same is true in reverse. Any change made to any file or folder **outside** the container within:
-
-```
-~/IOTstack/volumes/nodered/data
-```
-
-is mirrored at the same relative path **inside** the container at:
-
-```
-/data
-```
+This type of volume is a
+[bind-mount](https://docs.docker.com/storage/bind-mounts/), where the
+container's internal path is directly linked to the external path. All
+file-system operations, reads and writes, are mapped to directly to the files
+and folders at the external path.
 
 ### deleting persistent data
 
@@ -561,7 +542,7 @@ This is how **most** containers behave. There are exceptions so it's always a go
 
 !!! danger "Breaking update"
     Recent changes will require [manual steps](
-    https://github.com/SensorsIot/IOTstack/blob/master/README.md#significant-change-to-networking)
+    ../Updates/migration-network-change.md)
     or you may get an error like:  
     `ERROR: Service "influxdb" uses an undefined network "iotstack_nw"`
 

docs/Updates/Changelog.md

@@ -0,0 +1,26 @@
+## Latest
+<!-- what's in open pull requests that will be merged at an unknown date -->
+
+- New service: [Duckdns](../Containers/Duckdns.md), deprecates the
+  `duck/duck.sh` script.
+- Fixes to [bash aliases](../Basic_setup/Docker.md#aliases)
+- Documentation development made easier: [Writing documentation](
+  ../Developers/index.md#writing-documentation)
+
+## 2022-04-26
+
+- New service: [Syncthing](../Containers/Syncthing.md)
+- Zigbee2MQTT: [Service definition change](
+  ../Containers/Zigbee2MQTT.md#service-definition-change)
+- Dropping support for Home Assistant Supervised. Home Assistant **Container**
+  still available.
+- [Homebridge](../Containers/Homebridge.md) is now on port 8581
+- Documentation: Added: [Git Setup](../Developers/Git-Setup.md). Large changes
+  to: [Updates](../Updates/index.md), [InfluxDB](../Containers//InfluxDB.md),
+  [Grafana](../Containers/Grafana.md), [Pi-hole](../Containers/Pi-hole.md),
+  [Docker Logging](../Basic_setup/Docker.md#logging).
+
+## 2022-01-18
+
+- Networking change **requiring** [migration](
+  ../Updates/migration-network-change.md).