remove assumption user ID is 1000

On menu.sh start, store current UID and GID to .env, if they are missing.
Use these to run services that use a customized user.

.gitignore

@@ -5,7 +5,9 @@
 /.tmp/*
 __pycache__
 docker-compose.yml
+docker-compose.override.yml
 compose-override.yml
+.env
 postbuild.sh
 pre_backup.sh
 post_backup.sh

.templates/blynk_server/service.yml

@@ -7,8 +7,8 @@ blynk_server:
   restart: unless-stopped
   environment:
     - TZ=Etc/UTC
-    - IOTSTACK_UID=1000
-    - IOTSTACK_GID=1000
+    - IOTSTACK_UID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+    - IOTSTACK_GID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
   ports:
     - "8180:8080"
     - "8440:8440"

.templates/domoticz/service.yml

@@ -10,8 +10,8 @@ domoticz:
   restart: unless-stopped
   network_mode: bridge
   environment:
-    - PUID=1000
-    - PGID=1000
+    - PUID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+    - PGID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
     # - TZ=
     # - WEBROOT=domoticz
 

.templates/gitea/service.yml

@@ -6,8 +6,8 @@ gitea:
     - "7920:3000/tcp"
     - "2222:22/tcp"
   environment:
-    - USER_UID=1000
-    - USER_GID=1000
+    - USER_UID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+    - USER_GID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
   volumes:
     - ./volumes/gitea/data:/data
     - /etc/timezone:/etc/timezone:ro

.templates/heimdall/service.yml

@@ -2,8 +2,8 @@ heimdall:
   image: ghcr.io/linuxserver/heimdall
   container_name: heimdall
   environment:
-    - PUID=1000
-    - PGID=1000
+    - PUID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+    - PGID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
     - TZ=Europe/Paris
   volumes:
     - ./volumes/heimdall/config:/config

.templates/homebridge/service.yml

@@ -4,8 +4,8 @@ homebridge:
   restart: unless-stopped
   environment:
     - TZ=Etc/UTC
-    - PGID=1000
-    - PUID=1000
+    - PGID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
+    - PUID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
     - HOMEBRIDGE_CONFIG_UI=1
     - HOMEBRIDGE_CONFIG_UI_PORT=8581
   volumes:

.templates/homer/service.yml

@@ -2,8 +2,8 @@ homer:
   image: b4bz/homer:latest
   container_name: homer
   environment:
-    - UID=1000
-    - GID=1000
+    - UID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+    - GID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
   volumes:
     - ./volumes/homer/assets:/www/assets
   ports:

.templates/mariadb/service.yml

@@ -3,8 +3,8 @@ mariadb:
   container_name: mariadb
   environment:
     - TZ=Etc/UTC
-    - PUID=1000
-    - PGID=1000
+    - PUID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+    - PGID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
     - MYSQL_ROOT_PASSWORD=%randomAdminPassword%
     - MYSQL_DATABASE=default
     - MYSQL_USER=mariadbuser

.templates/n8n/service.yml

@@ -21,9 +21,9 @@ n8n:
 #           - N8N_BASIC_AUTH_ACTIVE=true
 #           - N8N_BASIC_AUTH_USER=<USER>
 #           - N8N_BASIC_AUTH_PASSWORD=<PASSWORD>
-
-#            - PGID=1000
-#            - PUID=1000
-#            - USBDEVICES=/dev/ttyAMA0
-#            - PACKAGES=mc
+#
+#           - PGID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
+#           - PUID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+#           - USBDEVICES=/dev/ttyAMA0
+#           - PACKAGES=mc
 

.templates/nextcloud/service.yml

@@ -23,8 +23,8 @@ nextcloud_db:
   restart: unless-stopped
   environment:
     - TZ=Etc/UTC
-    - PUID=1000
-    - PGID=1000
+    - PUID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+    - PGID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
     - MYSQL_ROOT_PASSWORD=%randomPassword%
     - MYSQL_PASSWORD=%randomMySqlPassword%
     - MYSQL_DATABASE=nextcloud

.templates/plex/service.yml

@@ -3,8 +3,8 @@ plex:
   container_name: plex
   network_mode: host
   environment:
-    - PUID=1000
-    - PGID=1000
+    - PUID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+    - PGID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
     - VERSION=docker
   volumes:
     - ./volumes/plex/config:/config

.templates/prometheus/service.yml

@@ -6,8 +6,8 @@ prometheus:
   ports:
     - "9090:9090"
   environment:
-    - IOTSTACK_UID=1000
-    - IOTSTACK_GID=1000
+    - IOTSTACK_UID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+    - IOTSTACK_GID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
   volumes:
     - ./volumes/prometheus/data:/prometheus
   command:

.templates/python/service.yml

@@ -4,8 +4,8 @@ python:
   restart: unless-stopped
   environment:
     - TZ=Etc/UTC
-    - IOTSTACK_UID=1000
-    - IOTSTACK_GID=1000
+    - IOTSTACK_UID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+    - IOTSTACK_GID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
   # ports:
   #   - "external:internal"
   volumes:

.templates/qbittorrent/service.yml

@@ -2,8 +2,8 @@
     image: linuxserver/qbittorrent
     container_name: qbittorrent
     environment:
-      - PUID=1000
-      - PGID=1000
+      - PUID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+      - PGID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
       - UMASK_SET=022
       - WEBUI_PORT=15080
     volumes:

.templates/syncthing/service.yml

@@ -3,8 +3,8 @@
     container_name: syncthing
     hostname: raspberrypi #optional
     environment:
-      - PUID=1000
-      - PGID=1000
+      - PUID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+      - PGID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
       - HOME=/app
       - TZ=Etc/UTC
     volumes:

.templates/transmission/service.yml

@@ -2,8 +2,8 @@ transmission:
   image: linuxserver/transmission
   container_name: transmission
   environment:
-    - PUID=1000
-    - PGID=1000
+    - PUID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+    - PGID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
     - TZ=Etc/UTC
   volumes:
     - ./volumes/transmission/config:/config

.templates/wireguard/service.yml

@@ -3,8 +3,8 @@ wireguard:
   image: ghcr.io/linuxserver/wireguard
   restart: unless-stopped
   environment:
-  - PUID=1000
-  - PGID=1000
+  - PUID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+  - PGID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
   - TZ=Etc/UTC
   - SERVERURL=your.dynamic.dns.name
   - SERVERPORT=51820

docs/Basic_setup/Backup-and-Restore.md

@@ -14,7 +14,9 @@ There are 2 ways to run backups:
 
 The command that's run from the command line can also be executed from a cronjob:
 
-```0 2 * * * cd /home/pi/IOTstack && /bin/bash ./scripts/backup.sh```
+```
+0 2 * * * cd /home/pi/IOTstack && /bin/bash ./scripts/backup.sh
+```
 
 The current directory of bash must be in IOTstack's directory, to ensure that it can find the relative paths of the files it's meant to back up. In the example above, it's assume that it's inside the `pi` user's home directory.
 
@@ -60,7 +62,14 @@ 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`
 
-**Important**: The restore script assumes that the IOTstack directory is fresh, as if it was just cloned. If it is not fresh, errors may occur, or your data may not correctly be restored even if no errors are apparent.
+**Important**:
+
+* The restore script assumes that the IOTstack directory is fresh, as if it was
+  just cloned. If it's not clean git clone, errors may occur, or your data may
+  not be restored correctly even if no errors are apparent.
+* When reinstalling Raspberry or migrating to a new installation, use the same
+  user and ID (usually pi and 1000) as when you created the backup. Changing
+  to another user ID is explicitly NOT supported.
 
 *Note*: It is suggested that you test that your backups can be restored after initially setting up, and anytime you add or remove a service. Major updates to services can also break backups.
 

docs/Basic_setup/index.md

@@ -17,9 +17,11 @@ IOTstack makes the following assumptions:
 1. Your hardware is a Raspberry Pi (typically a 3B+ or 4B).
 
 	* The Raspberry Pi Zero W2 has been tested with IOTstack. It works but the 512MB RAM means you should not try to run too many containers concurrently.
-    * Users have also [reported success
-      ](https://github.com/SensorsIot/IOTstack/issues/375) on Orange Pi
+	* Users have also [reported success](
+	  https://github.com/SensorsIot/IOTstack/issues/375) on Orange Pi
       Win/Plus.
+	* Most services will run on any Linux machine with Docker, but some have
+	  Raspberry Pi specific default configurations or dependencies.
 
 2. Your Raspberry Pi has a reasonably-recent version of 32-bit or 64-bit Raspberry Pi OS (aka "Raspbian") installed. You can download operating-system images:
 
@@ -28,21 +30,31 @@ IOTstack makes the following assumptions:
 	* [Prior releases](http://downloads.raspberrypi.org/raspios_armhf/images/)
       : This offers only "Raspberry Pi OS with desktop" images.
 
-3. Your operating system has been updated:
+3. You've done a "default" Raspberry Pi OS install, which automatically
+   satisfies:
+
+    - you log in as a regular user, not root. The actual username and its
+      numeric uid doesn't matter.
+    - this user has `sudo`-access, usually this is done by belonging to the
+      *sudo*-group.
+    - boot partition is mounted at `/boot`.
+
+4. Your operating system has been updated:
 
 	``` console
 	$ sudo apt update
 	$ sudo apt upgrade -y
 	```
 
-4. You are logged-in as the user "pi".
-5. User "pi" has the user ID 1000.
-6. The home directory for user "pi" is `/home/pi/`.
-7. IOTstack is installed at `/home/pi/IOTstack` (with that exact spelling).
-
-If the first three assumptions hold, assumptions four through six are Raspberry Pi defaults on a clean installation. The seventh is what you get if you follow these instructions faithfully.
+For brevity, this documentation also makes some guesses, but these aren't
+technical requirements. If you have a different choice, you'll just have to
+adjust the commands presented in these instructions to match the change. For
+first-time Linux users it's recommended to start with these:
 
-Please don't read these assumptions as saying that IOTstack will not run on other hardware, other operating systems, or as a different user. It is just that IOTstack gets most of its testing under these conditions. The further you get from these implicit assumptions, the more your mileage may vary.
+- You are logged-in as the user "pi".
+- The home directory for user "pi" is `/home/pi/`.
+- IOTstack is installed at `~/IOTstack` (with that exact spelling).
+- The system hostname is `raspberrypi`
 
 ## New installation
 

docs/Containers/Home-Assistant.md

@@ -124,8 +124,8 @@ your RPi hostname is raspberrypi)
 	    cap_add:
 	      - NET_ADMIN
 	    environment:
-	      - PUID=1000
-	      - PGID=1000
+	      - PUID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+	      - PGID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
 	      - TZ=Etc/UTC
 	      - URL=<yourdomain>.duckdns.org
 	      - SUBDOMAINS=wildcard

docs/Containers/NextCloud.md

@@ -27,8 +27,8 @@ nextcloud_db:
   restart: unless-stopped
   environment:
     - TZ=Etc/UTC
-    - PUID=1000
-    - PGID=1000
+    - PUID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+    - PGID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
     - MYSQL_ROOT_PASSWORD=«root_password»
     - MYSQL_PASSWORD=«user_password»
     - MYSQL_DATABASE=nextcloud

docs/Containers/Prometheus.md

@@ -237,11 +237,11 @@ The IOTstack implementation of *Prometheus* supports two environment variables:
 
 ```yaml
 environment:
-  - IOTSTACK_UID=1000
-  - IOTSTACK_GID=1000
+  - IOTSTACK_UID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+  - IOTSTACK_GID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
 ```
 
-Those variables control ownership of the [Configuration directory](#configDir) and its contents. Those environment variables are present in the standard IOTstack service definition for *Prometheus* and have the effect of assigning ownership to "pi:pi".
+Those variables control ownership of the [Configuration directory](#configDir) and its contents. Those environment variables are present in the standard IOTstack service definition for *Prometheus* and have the effect of assigning ownership to your current user, e.g. "pi".
 
 If you delete those environment variables from your *Compose* file, the [Configuration directory](#configDir) will be owned by "nobody:nobody"; otherwise the directory and its contents will be owned by whatever values you pass for those variables.
 

docs/Containers/Python.md

@@ -34,8 +34,8 @@ When you select Python in the menu:
 	  restart: unless-stopped
 	  environment:
 	  - TZ=Etc/UTC
-	  - IOTSTACK_UID=1000
-	  - IOTSTACK_GID=1000
+	  - IOTSTACK_UID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+	  - IOTSTACK_GID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
 	# ports:
 	#   - "external:internal"
 	  volumes:
@@ -48,18 +48,20 @@ The service definition contains a number of customisation points:
 
 1. `restart: unless-stopped` assumes your Python script will run in an infinite loop. If your script is intended to run once and terminate, you should remove this directive.
 2. `TZ=Etc/UTC` should be set to your local time-zone. Never use quote marks on the right hand side of a `TZ=` variable.
-3. If you are running as a different user ID, you may want to change both `IOTSTACK_UID` and `IOTSTACK_GID` to appropriate values.
+3.  If you need a different user ID, you may want to change both `IOTSTACK_UID`
+    and `IOTSTACK_GID` to appropriate values. By default they are defined to be
+    the same as the current user when you run the menu. Defaults are stored in
+    `~/IOTstack/.env`, but don't edit that file. Make your edits directly to
+    `docker-compose.yml`.
 
-	Notes:
+    !!! note
 
-	* Don't use user and group *names* because these variables are applied *inside* the container where those names are (probably) undefined.
-	* The only thing these variables affect is the ownership of:
-
-		```
-		~/IOTstack/volumes/python/app
-		```
-
-		and its contents. If you want everything to be owned by root, set both of these variables to zero (eg `IOTSTACK_UID=0`).
+        * Don't use user and group *names* because these variables are applied
+          *inside* the container where those names are (probably) undefined.
+        * The only thing these variables affect is the ownership of
+          `~/IOTstack/volumes/python/app` and its contents. If you want
+          everything to be owned by root, set both of these variables to zero
+          (e.g. `IOTSTACK_UID=0`).
 
 4. If your Python script listens to data-communications traffic, you can set up the port mappings by uncommenting the `ports:` directive.
 
@@ -444,8 +446,8 @@ Proceed like this:
 	  restart: unless-stopped                     restart: unless-stopped
 	  environment:                                environment:
 	    - TZ=Etc/UTC                                - TZ=Etc/UTC
-	    - IOTSTACK_UID=1000                         - IOTSTACK_UID=1000
-	    - IOTSTACK_GID=1000                         - IOTSTACK_GID=1000
+	    - IOTSTACK_UID=${IOTSTACK_UID:?...}         - IOTSTACK_UID=${IOTSTACK_UID:?...}
+	    - IOTSTACK_GID=${IOTSTACK_GID:?...}         - IOTSTACK_GID=${IOTSTACK_GID:?...}
 	  # ports:                                    # ports:
 	  #   - "external:internal"                   #   - "external:internal"
 	  volumes:                                    volumes:

docs/Containers/WireGuard.md

@@ -41,8 +41,8 @@ wireguard:
   image: ghcr.io/linuxserver/wireguard
   restart: unless-stopped
   environment:
-  - PUID=1000
-  - PGID=1000
+  - PUID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+  - PGID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
   - TZ=Etc/UTC
   - SERVERURL=your.dynamic.dns.name
   - SERVERPORT=51820
@@ -247,8 +247,8 @@ You will need to create the `compose-override.yml` **before** running the menu t
 	services:
 	  wireguard:
 	    environment:
-	    - PUID=1000
-	    - PGID=1000
+	    - PUID=${IOTSTACK_UID:?IOTSTACK_UID must be defined in ~/IOTstack/.env}
+	    - PGID=${IOTSTACK_GID:?IOTSTACK_GID must be defined in ~/IOTstack/.env}
 	    - TZ=Australia/Sydney
 	    - SERVERURL=downunda.duckdns.org
 	    - SERVERPORT=51820