docs: move network migration to its own page

Author: ukkopahis

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

@@ -542,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

@@ -23,5 +23,4 @@
 ## 2022-01-18
 
 - Networking change **requiring** [migration](
-  https://github.com/SensorsIot/IOTstack/#significant-change-to-networking).
-
+  ../Updates/migration-network-change.md).

docs/Updates/index.md

@@ -122,7 +122,7 @@ Periodically updates are made to project which include new or modified container
 
 !!! 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/migration-network-change.md

@@ -0,0 +1,64 @@
+# Migration: network change
+
+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.
+
+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.