Documentation fixes and improvements

.github/workflows/main.yml

@@ -9,10 +9,11 @@ jobs:
     name: Deploy docs
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout master
-        uses: actions/checkout@v1
-
-      - name: Deploy docs
-        uses: mhausenblas/mkdocs-deploy-gh-pages@master
-        env:
-          PERSONAL_TOKEN: ${{ secrets.PERSONAL_TOKEN }}
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+      - run: pip install mkdocs-material
+      - run: pip install mkdocs-redirects
+      - run: pip install mkdocs-git-revision-date-localized-plugin
+      - run: mkdocs gh-deploy --force

.templates/wireguard/use-container-dns.sh

@@ -1,8 +1,9 @@
 # Forward DNS requests from remote WireGuard clients to the default
 # gateway on the internal bridged network that the WireGuard container
-# is attached to. This results in queries being sent to any other
-# container on the same internal bridged network that is listening
-# on port 53 (eg PiHole, AdGuardHome or bind9).
+# is attached to. The gateway routes queries out from the bridged network to
+# the host's network. This results in queries being sent to any daemon or
+# container that is listening on host port 53 (eg PiHole, AdGuardHome, dnsmasq
+# or bind9).
 #
 # Acknowledgement: @ukkopahis
 

docs/Accessing-your-Device-from-the-internet.md → docs/Basic_setup/Accessing-your-Device-from-the-internet.md

@@ -6,14 +6,14 @@ From time to time the IP address that your ISP assigns changes and it's difficul
 
 Secondly, how do you get into your home network? Your router has a firewall that is designed to keep the rest of the internet out of your network to protect you. The solution to that is a Virtual Private Network (VPN) or "tunnel". 
 
-## <a name="dynamicDNS"> Dynamic DNS </a>
+## Dynamic DNS
 
 There are two parts to a Dynamic DNS service:
 
 1. You have to register with a Dynamic DNS service provider and obtain a domain name that is not already taken by someone else.
 2. Something on your side of the network needs to propagate updates so that your chosen domain name remains in sync with your router's dynamically-allocated public IP address.
 
-### <a name="registerDDNS"> Register with a Dynamic DNS service provider </a>
+### Register with a Dynamic DNS service provider
 
 The first part is fairly simple and there are quite a few Dynamic DNS service providers including:
 
@@ -24,7 +24,7 @@ The first part is fairly simple and there are quite a few Dynamic DNS service pr
 
 Some router vendors also provide their own built-in Dynamic DNS capabilities for registered customers so it's a good idea to check your router's capabilities before you plough ahead.
 
-### <a name="propagateDDNS"> Dynamic DNS propagation </a>
+### Dynamic DNS propagation
 
 The "something" on your side of the network propagating WAN IP address changes can be either:
 
@@ -39,7 +39,7 @@ A behind-the-router technique usually relies on sending updates according to a s
 
 > This seems to be a problem for DuckDNS which takes a beating because almost every person using it is sending an update bang-on five minutes.
 
-### <a name="duckDNSclient"> DuckDNS client </a>
+### DuckDNS client
 
 IOTstack provides a solution for DuckDNS. The best approach to running it is:
 
@@ -99,7 +99,7 @@ A null result indicates failure so check your work.
 
 Remember, the Domain Name System is a *distributed* database. It takes *time* for changes to propagate. The response you get from directing a query to ns1.duckdns.org may not be the same as the response you get from any other DNS server. You often have to wait until cached records expire and a recursive query reaches the authoritative DuckDNS name-servers.
 
-#### <a name="duckDNSauto"> Running the DuckDNS client automatically </a>
+#### Running the DuckDNS client automatically
 
 The recommended arrangement for keeping your Dynamic DNS service up-to-date is to invoke `duck.sh` from `cron` at five minute intervals.
 
@@ -152,7 +152,7 @@ $ cat /dev/null >~/Logs/duck.log
 
 ### WireGuard
 
-WireGuard is supplied as part of IOTstack. See [WireGuard documentation](https://sensorsiot.github.io/IOTstack/Containers/WireGuard.html).
+WireGuard is supplied as part of IOTstack. See [WireGuard documentation](../Containers/WireGuard.md).
 
 ### PiVPN
 

docs/Backup-and-Restore.md → docs/Basic_setup/Backup-and-Restore.md

@@ -8,6 +8,7 @@ The backup command can be executed from IOTstack's menu, or from a cronjob.
 To ensure that all your data is saved correctly, the stack should be brought down. This is mainly due to databases potentially being in a state that could cause data loss.
 
 There are 2 ways to run backups:
+
 * From the menu: `Backup and Restore` > `Run backup`
 * Running the following command: `bash ./scripts/backup.sh`
 
@@ -21,6 +22,7 @@ The current directory of bash must be in IOTstack's directory, to ensure that it
 ```
 ./scripts/backup.sh {TYPE=3} {USER=$(whoami)}
 ```
+
 * Types:
   * 1 = Backup with Date
     * A tarball file will be created that contains the date and time the backup was started, in the filename.
@@ -33,10 +35,12 @@ The current directory of bash must be in IOTstack's directory, to ensure that it
       If this parameter is not supplied when run as root, the script will ask for the username as input
 
 Backups:
+
   * You can find the backups in the ./backups/ folder. With rolling being in ./backups/rolling/ and date backups in ./backups/backup/
   * Log files can also be found in the ./backups/logs/ directory.
 
 ### Examples:
+
   * `./scripts/backup.sh`
   * `./scripts/backup.sh 3`
 
@@ -52,6 +56,7 @@ This will only produce a backup in the rollowing folder and change all the permi
 
 ## Restore
 There are 2 ways to run a restore:
+
 * From the menu: `Backup and Restore` > `Restore from backup`
 * Running the following command: `bash ./scripts/restore.sh`
 
@@ -64,6 +69,7 @@ There are 2 ways to run a restore:
 ./scripts/restore.sh {FILENAME=backup.tar.gz} {noask}
 ```
 The restore script takes 2 arguments:
+
 * Filename: The name of the backup file. The file must be present in the `./backups/` directory, or a subfolder in it. That means it should be moved from `./backups/backup` to `./backups/`, or that you need to specify the `backup` portion of the directory (see examples)
 * NoAsk: If a second parameter is present, is acts as setting the no ask flag to true. 
 

docs/Custom.md → docs/Basic_setup/Custom.md

@@ -125,7 +125,7 @@ services:
     environment:
 ```
 
-This will remove the default environment variables set in the template, and tell docker-compose to use the variables specified in your file. It is not mandatory that the *.env file be placed in the service's service directory, but is strongly suggested. Keep in mind the [PostBuild Script](https://sensorsiot.github.io/IOTstack/PostBuild-Script) functionality to automatically copy your *.env files into their directories on successful build if you need to.
+This will remove the default environment variables set in the template, and tell docker-compose to use the variables specified in your file. It is not mandatory that the *.env file be placed in the service's service directory, but is strongly suggested. Keep in mind the [PostBuild Script](../Developers/PostBuild-Script.md) functionality to automatically copy your *.env files into their directories on successful build if you need to.
 
 ### Adding custom services
 

docs/Default-Configs.md → docs/Basic_setup/Default-Configs.md

@@ -1,4 +1,4 @@
-# Build Stack Default Passwords for Services
+# Default Passwords and ports
 
 Here you can find a list of the default configurations for IOTstack for quick referece.
 

docs/New-Menu-Release-Notes.md → docs/Basic_setup/Updates/New-Menu-Release-Notes.md

@@ -8,7 +8,8 @@ There are many features that are needing to be introduced into the new menu syst
 
 ## Breaking changes
 There are a few changes that you need to be aware of:
-* Docker Environmental `*.env` files are no longer a thing by default. Everything needed is specified in the service.yml file, you can still optionally use them though either with [Custom Overrides](https://sensorsiot.github.io/IOTstack/Custom) or with the [PostBuild](https://sensorsiot.github.io/IOTstack/PostBuild-Script) script. Specific config files for certain services still work as they once did.
+
+* Docker Environmental `*.env` files are no longer a thing by default. Everything needed is specified in the service.yml file, you can still optionally use them though either with [Custom Overrides](../Custom.md) or with the [PostBuild](../../Developers/PostBuild-Script.md) script. Specific config files for certain services still work as they once did.
 * Python 3, pip3, PyYAML and Blessed are all required to be installed.
 * Not backwards compatible with old menu system. You will be able to switch back to the old menu system for a period of time by changing to the `old-menu` branch. It will be unmaintained except for critical updates. It will eventually be removed - but not before everyone is ready to leave it.
 
@@ -26,4 +27,4 @@ There are a few changes that you need to be aware of:
 * Removed env files
 * Backup and restoring more streamlined
 * Documentation updated for all services
-* No longer needs to be installed in the home directory `~`.
+* No longer needs to be installed in the home directory `~`.

docs/Updating-the-Project.md → docs/Basic_setup/Updates/Updating-the-Project.md

@@ -1,9 +1,36 @@
 # Updating the project
-**If you ran the git checkout -- 'git ls-files -m' as suggested in the old wiki entry then please check your duck.sh because it removed your domain and token**
-
 
 Periodically updates are made to project which include new or modified container template, changes to backups or additional features. As these are released your local copy of this project will become out of date. This section deals with how to bring your project to the latest published state.
 
+## Quick instructions
+
+1. backup your current settings: `cp docker-compose.yml docker-compose.yml.bak`
+2. check `git status` for any local changes you may have made to project files. Save and preserve your changes by doing a commit: `git commit -a -m "local customization"`. Or revert them using: `git checkout -- path/to/changed_file`.
+3. update project files from github: `git pull origin master -r`
+4. get latest images from the web: `docker-compose pull`
+5. rebuild localy created images from new Dockerfiles: `docker-compose build --pull --no-cache`
+6. update running containers to latest: `docker-compose up --build -d`
+
+*Troubleshooting:* if a container fails to restart after update
+
+* try restarting the whole stack: `docker-compose restart`
+* backup your stack settings: `cp docker-compose.yml docker-compose.yml.bak`
+* Check log output of the failing service: `docker-compose logs *service-name*`
+    * try googling and fixing problems in docker-compose.yml manually.
+* try recreating the failing service definition using menu.sh:
+    1. `./menu.sh`, select Build Stack, unselect the failing service, press
+       enter to build, and then exit.
+    2. `./menu.sh`, select Build Stack, select the service back again, press
+       enter to build, and then exit.
+    3. Try starting now: `docker-compose up -d`
+* Go to the [IOTStack Discord](https://discord.gg/ZpKHnks) and describe your
+  problem. We're happy to help.
+
+## Details, partly outdated
+
+!!! warning
+    If you ran `git checkout -- 'git ls-files -m'` as suggested in the old wiki entry then please check your duck.sh because it removed your domain and token
+
 Git offers build in functionality to fetch the latest changes.
 
 `git pull origin master` will fetch the latest changes from GitHub without overwriting files that you have modified yourself. If you have done a local commit then your project may to handle a merge conflict.
@@ -18,4 +45,4 @@ With the new latest version of the project you can now use the menu to build you
 
 ![image](https://user-images.githubusercontent.com/46672225/68646024-8fee2f80-0522-11ea-8b6e-f1d439a5be7f.png)
 
-After your stack had been rebuild you can run `docker-compose up -d` to pull in the latest changes. If you have not update your images in a while consider running the `./scripts/update.sh` to get the latest version of the image from Docker hub as well
+After your stack had been rebuild you can run `docker-compose up -d` to pull in the latest changes. If you have not update your images in a while consider running the `./scripts/update.sh` to get the latest version of the image from Docker hub as well

docs/gcgarner-migration.md → docs/Basic_setup/Updates/gcgarner-migration.md

@@ -6,9 +6,9 @@ Migrating to SensorsIot/IOTstack was fairly easy when this repository was first
 
 The probability of conflicts developing increases as a function of time since the fork. Conflicts were and are pretty much inevitable so a more involved procedure is needed.
 
-## <a name="migrationSteps"> Migration Steps </a>
+## Migration Steps
 
-### <a name="checkAssumptions"> Step 1 – Check your assumptions </a>
+### Step 1 – Check your assumptions
 
 Make sure that you are, *actually*, on gcgarner. Don't assume!
 
@@ -20,7 +20,7 @@ origin	https://github.com/gcgarner/IOTstack.git (push)
 
 Do not proceed if you don't see those URLs!
 
-### <a name="downStack"> Step 2 – Take IOTstack down </a>
+### Step 2 – Take IOTstack down
 
 Take your stack down. This is not *strictly* necessary but we'll be moving the goalposts a bit so it's better to be on the safe side.
 
@@ -29,22 +29,22 @@ $ cd ~/IOTstack
 $ docker-compose down
 ```
 
-### <a name="chooseMigrationMethod"> Step 3 – Choose your migration method </a>
+### Step 3 – Choose your migration method
 
 There are two basic approaches to switching from gcgarner/IOTstack to SensorsIot/IOTstack:
 
-- [Migration by changing upstream repository](#migrateChangeUpstream)
-- [Migration by clone and merge](#migrateCloneMerge)
+- [Migration by changing upstream repository](#migration-option-1-change-upstream-repository)
+- [Migration by clone and merge](#migration-option-2-clone-and-merge)
 
 You can think of the first as "working *with* git" while the second is "using brute force".
 
 The first approach will work if you haven't tried any other migration steps and/or have not made too many changes to items in your gcgarner/IOTstack that are under git control.
 
-If you are already stuck or you try the first approach and get a mess, or it all looks far too hard to sort out, then try the [Migration by clone and merge](#migrateCloneMerge) approach.
+If you are already stuck or you try the first approach and get a mess, or it all looks far too hard to sort out, then try the [Migration by clone and merge](#migration-option-2-clone-and-merge) approach.
 
-#### <a name="migrateChangeUpstream"> Migration Option 1 – change upstream repository </a>
+#### Migration Option 1 – change upstream repository
 
-##### <a name="checkLocalChanges"> Check for local changes </a>
+##### Check for local changes
 
 Make sure you are on the master branch (you probably are so this is just a precaution), and then see if Git thinks you have made any local changes:
 
@@ -93,15 +93,15 @@ The simplest way to deal with modified files is to rename them to move them out
 		menu.sh.jqh
 	```
 
-##### <a name="synchroniseGcgarner"> Synchronise with gcgarner on GitHub </a>
+##### Synchronise with gcgarner on GitHub
 
 Make sure your local copy of gcgarner is in sync with GitHub.
 
 ```
 $ git pull
 ```
 
-##### <a name="removeUpstream"> Get rid of any upstream reference </a>
+##### Get rid of any upstream reference
 
 There may or may not be any "upstream" set. The most likely reason for this to happen is if you used your local copy as the basis of a Pull Request.
 
@@ -111,15 +111,15 @@ The next command will probably return an error, which you should ignore. It's ju
 $ git remote remove upstream
 ```
 
-##### <a name="pointToSensorsIoT"> Point to SensorsIot </a>
+##### Point to SensorsIot
 
 Change your local repository to point to SensorsIot.
 
 ```
 $ git remote set-url origin https://github.com/SensorsIot/IOTstack.git
 ```
 
-##### <a name="syncSensorsIoT"> Synchronise with SensorsIot on GitHub </a>
+##### Synchronise with SensorsIot on GitHub
 
 This is where things can get a bit tricky so please read these instructions carefully **before** you proceed.
 
@@ -174,19 +174,19 @@ Auto-merging .templates/someRandomService/service.yml
 
 If you don't use `someRandomService` then you could safely ignore this on the basis that it was "probably right". However, if you did use that service and it started to misbehave after migration, you would know that the `service.yml` file was a good place to start looking for explanations.
 
-##### <a name="finishWithPull"> Finish with a pull </a>
+##### Finish with a pull
 
 At this point, only the migrated master branch is present on your local copy of the repository. The next command brings you fully in-sync with GitHub:
 
 ```
 $ git pull
 ```
 
-#### <a name="migrateCloneMerge"> Migration Option 2 – clone and merge </a>
+#### Migration Option 2 – clone and merge
 
 If you have been following the process correctly, your IOTstack will already be down.
 
-##### <a name="renameOldIOTstack"> Rename your existing IOTstack folder </a>
+##### Rename your existing IOTstack folder
 
 Move your old IOTstack folder out of the way, like this:
 
@@ -199,7 +199,7 @@ Note:
 
 * You should not need `sudo` for the `mv` command but it is OK to use it if necessary.
 
-##### <a name="fetchCleanClone"> Fetch a clean clone of SensorsIot/IOTstack </a>
+##### Fetch a clean clone of SensorsIot/IOTstack
 
 ```
 $ git clone https://github.com/SensorsIot/IOTstack.git ~/IOTstack
@@ -240,7 +240,7 @@ Observe what is **not** there:
 
 From this, it should be self-evident that a clean checkout from GitHub is the factory for *all* IOTstack installations, while the contents of `backups`, `services`, `volumes` and `docker-compose.yml` represent each user's individual choices, configuration options and data.
 
-##### <a name="mergeOldWithNew"> Merge old into new </a>
+##### Merge old into new
 
 Execute the following commands:
 
@@ -272,7 +272,7 @@ There is no need to migrate the `backups` directory. You are better off creating
 $ mkdir ~/IOTstack/backups
 ```
 
-### <a name="chooseMenu"> Step 4 – Choose your menu </a>
+### Step 4 – Choose your menu
 
 If you have reached this point, you have migrated to SensorsIot/IOTstack where you are on the "master" branch. This implies "new menu".
 
@@ -353,15 +353,15 @@ Although you can freely change branches, it's probably not a good idea to try to
 
 Even so, nothing will change **until** you run your chosen menu to completion and allow it to generate a new `docker-compose.yml`.
 
-### <a name="upStack"> Step 5 – Bring up your stack </a>
+### Step 5 – Bring up your stack
 
 Unless you have gotten ahead of yourself and have already run the menu (old or new) then nothing will have changed in the parts of your `~/IOTstack` folder that define your IOTstack implementation. You can safely:
 
 ```
 $ docker-compose up -d
 ```
 
-## <a name="seeAlso"> See also </a>
+## See also
 
 There is another gist [Installing Docker for IOTstack](https://gist.github.com/Paraphraser/d119ae81f9e60a94e1209986d8c9e42f) which explains how to overcome problems with outdated Docker and Docker-Compose installations.