Merge pull request #466 from ukkopahis/doc-improvements

Documentation fixes and improvements

.github/workflows/main.yml

@@ -9,10 +9,9 @@ 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:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+      - run: pip3 install -r requirements-mkdocs.txt
+      - 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/Basic_setup/What-is-sudo.md

@@ -0,0 +1,47 @@
+# What is sudo?
+
+Many first-time users of IOTstack get into difficulty by misusing the `sudo` command. The problem is best understood by example. In the following, you would expect `~` (tilde) to expand to `/home/pi`. It does:
+
+```bash
+$ echo ~/IOTstack
+/home/pi/IOTstack
+```
+
+The command below sends the same `echo` command to `bash` for execution. This is what happens when you type the name of a shell script. You get a new instance of `bash` to run the script:
+
+```bash
+$ bash -c 'echo ~/IOTstack'
+/home/pi/IOTstack
+```
+
+Same answer. Again, this is what you expect. But now try it with `sudo` on the front:
+
+```bash
+$ sudo bash -c 'echo ~/IOTstack'
+/root/IOTstack
+```
+
+Different answer. It is different because `sudo` means "become root, and then run the command". The process of becoming root changes the home directory, and that changes the definition of `~`.
+
+Any script designed for working with IOTstack assumes `~` (or the equivalent `$HOME` variable) expands to `/home/pi`. That assumption is invalidated if the script is run by `sudo`.
+
+Of necessity, any script designed for working with IOTstack will have to invoke `sudo` **inside** the script **when it is required**. You do not need to second-guess the script's designer.
+
+Please try to minimise your use of `sudo` when you are working with IOTstack. Here are some rules of thumb:
+
+1. Is what you are about to run a script? If yes, check whether the script already contains `sudo` commands. Using `menu.sh` as the example:
+
+	```bash
+	$ grep -c 'sudo' ~/IOTstack/menu.sh
+	28
+	```
+
+	There are numerous uses of `sudo` within `menu.sh`. That means the designer thought about when `sudo` was needed.
+
+2. Did the command you **just executed** work without `sudo`? Note the emphasis on the past tense. If yes, then your work is done. If no, and the error suggests elevated privileges are necessary, then re-execute the last command like this:
+
+	```bash
+	$ sudo !!
+	```
+
+It takes time, patience and practice to learn when `sudo` is **actually** needed. Over-using `sudo` out of habit, or because you were following a bad example you found on the web, is a very good way to find that you have created so many problems for yourself that will need to reinstall your IOTstack. *Please* err on the side of caution!