Add offline installation support for air-gapped devices

.gitignore

@@ -319,6 +319,9 @@ pyrightconfig.json
 # Custom
 release
 release.tar.gz
+
+# Offline install bundles
+dweos-offline*.tar.gz
 **/device_settings.json
 **/server_preferences.json
 .env

README.md

@@ -10,6 +10,30 @@ To install for any *supported* Linux system, run the following command:
 
 `curl -s https://raw.githubusercontent.com/DeepwaterExploration/DWE_OS_2/main/install.sh | sudo bash -s`
 
+### Installing or updating a device with no internet access
+
+Build a bundle on a machine that has internet, then push it to the device over
+SSH. The device never reaches out to GitHub, PyPI or apt:
+
+```sh
+./deploy-offline.sh pi@192.168.2.2
+```
+
+If the device is not reachable from the machine with internet either, build the
+bundle and carry it across yourself:
+
+```sh
+# on the machine with internet, describing the device
+./package-offline.sh --arch aarch64 --python 3.11 --glibc 2.36
+
+# on the device
+tar -xzf dweos-offline-*.tar.gz
+sudo ./dweos-offline/install-offline.sh
+```
+
+Python packages are updated from the bundle's wheelhouse, so dependency changes
+ship with the update. See [docs/offline-update.md](docs/offline-update.md).
+
 ### Raspberry Pi Hardware PWM
 
 In order to enable hardware PWM on your Raspberry Pi, you need to edit `/boot/firmware/config.txt`. See [Raspberry Pi documentation](https://www.raspberrypi.com/documentation/computers/config_txt.html) for more information.

create_release.sh

@@ -39,7 +39,11 @@ echo "Successfully packaged frontend"
 cp run_release.py release
 cp install_requirements.sh release
 cp create_venv.sh release
+cp install-local.sh release
 cp run_release.sh release
 cp -r service release
 
+# Record the version so the installer can report what it just installed
+python3 -c "import json; print(json.load(open('frontend/package.json'))['version'])" > release/VERSION
+
 tar -czvf release.tar.gz release

create_venv.sh

@@ -1,11 +1,119 @@
 #!/bin/bash
 
-echo "Creating virtual python environment in .venv directory"
+set -e
 
-python3 -m venv .venv
+VENV_DIR=".venv"
+REQUIREMENTS="backend_py/requirements.txt"
+PYTHON_BIN="python3"
+WHEELHOUSE=""
+RECREATE=0
+UPGRADE=1
+
+usage() {
+    cat <<'USAGE'
+Usage: create_venv.sh [options]
+
+Creates (or refreshes) the Python virtual environment used by DWE OS.
+
+Options:
+  --venv DIR           Virtual environment directory (default: .venv)
+  --requirements FILE  Requirements file (default: backend_py/requirements.txt)
+  --python BIN         Python interpreter used to create the venv (default: python3)
+  --wheelhouse DIR     Install from a local directory of wheels instead of PyPI.
+                       Implies a fully offline pip run (--no-index).
+  --recreate           Delete and rebuild the virtual environment from scratch
+  --no-upgrade         Leave already-satisfied packages at their current version
+  -h, --help           Show this help
+USAGE
+}
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --venv)
+            VENV_DIR="$2"
+            shift 2
+            ;;
+        --requirements)
+            REQUIREMENTS="$2"
+            shift 2
+            ;;
+        --python)
+            PYTHON_BIN="$2"
+            shift 2
+            ;;
+        --wheelhouse)
+            WHEELHOUSE="$2"
+            shift 2
+            ;;
+        --recreate)
+            RECREATE=1
+            shift
+            ;;
+        --no-upgrade)
+            UPGRADE=0
+            shift
+            ;;
+        -h | --help)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1" >&2
+            usage >&2
+            exit 1
+            ;;
+    esac
+done
+
+if [ ! -f "$REQUIREMENTS" ]; then
+    echo "Error: requirements file not found: $REQUIREMENTS" >&2
+    exit 1
+fi
+
+PIP_ARGS=()
+if [ -n "$WHEELHOUSE" ]; then
+    if [ ! -d "$WHEELHOUSE" ]; then
+        echo "Error: wheelhouse directory not found: $WHEELHOUSE" >&2
+        exit 1
+    fi
+    # Absolute path, since pip is invoked after the venv is activated
+    WHEELHOUSE=$(cd "$WHEELHOUSE" && pwd)
+    PIP_ARGS+=(--no-index --find-links "$WHEELHOUSE")
+    echo "Installing Python packages offline from $WHEELHOUSE"
+fi
+
+if [ "$UPGRADE" -eq 1 ]; then
+    PIP_ARGS+=(--upgrade)
+fi
+
+if [ "$RECREATE" -eq 1 ] && [ -d "$VENV_DIR" ]; then
+    echo "Removing existing virtual environment in $VENV_DIR"
+    rm -rf "$VENV_DIR"
+fi
+
+if [ -x "$VENV_DIR/bin/python3" ]; then
+    echo "Reusing existing virtual environment in $VENV_DIR directory"
+else
+    echo "Creating virtual python environment in $VENV_DIR directory"
+    # A leftover, half-built venv would make the next step fail in confusing ways
+    rm -rf "$VENV_DIR"
+    "$PYTHON_BIN" -m venv "$VENV_DIR"
+fi
+
+if [ ! -x "$VENV_DIR/bin/pip" ]; then
+    echo "Error: $VENV_DIR has no pip. Install the python3-venv package and retry." >&2
+    exit 1
+fi
+
+# Keep pip itself current where we can. A stale pip cannot read newer wheel
+# metadata, but a failure here is never a reason to abort the install.
+if [ -n "$WHEELHOUSE" ]; then
+    "$VENV_DIR/bin/pip" install --no-index --find-links "$WHEELHOUSE" --upgrade pip ||
+        echo "Note: pip not upgraded (no newer pip wheel in the wheelhouse)"
+fi
 
 echo "Installing requirements..."
 
-. .venv/bin/activate && pip install -r backend_py/requirements.txt
+"$VENV_DIR/bin/pip" install "${PIP_ARGS[@]}" -r "$REQUIREMENTS"
 
-echo "Virtual environment created."
+echo "Virtual environment ready."