Refactor golden image handling in backup upload process</message>

<message>Update the _set_golden_from_path function to improve the handling of existing golden image files. Replace the existing unlink logic with a more robust method that safely removes files or broken symlinks using the missing_ok parameter. This change enhances the reliability of the backup upload process by ensuring that stale references are properly cleared before setting a new golden image path.
2026-02-24 00:19:40 +02:00
parent df180120aa
commit 808fbf5c7c
136 changed files with 407837 additions and 2 deletions
--- a/emmc-provisioning/docs/BACKUP-DEVICE-CONFIG-AUDIT.md
+++ b/emmc-provisioning/docs/BACKUP-DEVICE-CONFIG-AUDIT.md
@@ -0,0 +1,451 @@
+# reTerminal DM4 — Backup Device Configuration Audit
+
+> **Date:** 2026-02-23  
+> **Source device:** 10.20.50.147 (via jump host 10.20.30.153)  
+> **Purpose:** Document all manual configuration found on the old backup image.
+
+---
+
+## 1. Operating System
+
+| Property | Value |
+|----------|-------|
+| **Distro** | Debian GNU/Linux 13 (trixie) — full version 13.2 |
+| **Kernel** | 6.12.62+rpt-rpi-v8 (aarch64, PREEMPT, Raspberry Pi patched) |
+| **Hardware** | Raspberry Pi Compute Module 4 Rev 1.1 |
+| **Hostname** | `raspberrypi` (not changed from default) |
+| **Locale** | `en_US.UTF-8` (all categories) |
+| **Timezone** | `Asia/Nicosia` (EET, +0200) |
+| **NTP** | Active via `systemd-timesyncd` |
+| **Root filesystem** | `/dev/mmcblk0p2` ext4, 29 GB total, 11 GB used (39%) |
+| **Boot partition** | `/dev/mmcblk0p1` vfat, mounted at `/boot/firmware` |
+| **Swap** | zram0, ~2 GB (compressed RAM swap) |
+| **RAM** | 7.6 GiB total |
+
+---
+
+## 2. User Accounts
+
+| User | UID | Shell | Home | Notes |
+|------|-----|-------|------|-------|
+| `pi` | 1000 | `/bin/bash` | `/home/pi` | Primary user, passwordless sudo |
+| `root` | 0 | `/bin/bash` | `/root` | Standard |
+| `lightdm` | 104 | `/bin/false` | `/var/lib/lightdm` | Display manager service account |
+
+### pi user groups
+
+`pi adm dialout cdrom sudo audio video plugdev games users input render netdev spi i2c gpio lpadmin`
+
+### Sudoers
+
+- `pi ALL=(ALL) NOPASSWD: ALL` — full passwordless sudo.
+
+---
+
+## 3. Boot Configuration
+
+### `/boot/firmware/config.txt`
+
+Key non-default settings:
+
+```ini
+# Hardware interfaces
+dtparam=audio=on
+dtparam=i2c_arm=on
+dtparam=i2c_vc=on
+dtparam=i2s=on
+dtparam=spi=on
+enable_uart=1
+
+# Display
+display_auto_detect=0          # DSI auto-detect disabled (manual overlay)
+disable_fw_kms_setup=1
+max_framebuffers=2
+disable_overscan=1
+ignore_lcd=1
+
+# CM4 USB host mode
+otg_mode=1                     # [cm4] section
+
+# Antenna
+dtparam=ant2                   # External antenna
+
+# Overlays
+dtoverlay=dwc2,dr_mode=host
+dtoverlay=i2c1,pins_2_3
+dtoverlay=i2c3,pins_4_5
+dtoverlay=imx219,cam0          # Camera module
+dtoverlay=vc4-kms-v3d          # GPU/KMS driver
+dtoverlay=reTerminal-DM        # Seeed reTerminal DM overlay
+```
+
+### `/boot/firmware/cmdline.txt`
+
+```
+console=tty1 root=PARTUUID=5c5604eb-02 rootfstype=ext4 fsck.repair=yes rootwait
+quiet splash plymouth.ignore-serial-consoles cfg80211.ieee80211_regdom=CY
+logo.nologo vt.global_cursor_default=0 console=tty3 loglevel=0
+```
+
+Notable flags:
+- `quiet splash` — silent boot with Plymouth splash
+- `cfg80211.ieee80211_regdom=CY` — WiFi regulatory domain set to Cyprus
+- `logo.nologo` — kernel logo hidden
+- `vt.global_cursor_default=0` — no blinking cursor on VT
+- `console=tty3 loglevel=0` — boot messages redirected, minimal logging
+
+### Device Tree Overlay
+
+The Seeed `reTerminal-DM.dtbo` overlay is installed at `/boot/firmware/overlays/reTerminal-DM.dtbo`.
+
+---
+
+## 4. Display & Desktop Environment
+
+### Session Stack
+
+| Component | Value |
+|-----------|-------|
+| **Display manager** | LightDM 1.32.0 |
+| **Greeter** | `pi-greeter-labwc` |
+| **User session** | `rpd-labwc` (Raspberry Pi Desktop on Wayland) |
+| **Compositor** | labwc 0.9.2 (wlroots 0.19-based Wayland compositor) |
+| **XWayland** | Running for X11 app compatibility |
+
+### LightDM Configuration (`/etc/lightdm/lightdm.conf`)
+
+```ini
+[Seat:*]
+greeter-session=pi-greeter-labwc
+greeter-hide-users=false
+user-session=rpd-labwc
+display-setup-script=/usr/share/dispsetup.sh
+autologin-user=pi
+autologin-session=rpd-labwc
+```
+
+- Auto-login enabled for user `pi`.
+- Display setup script is a no-op (`exit 0`).
+
+### Display Rotation — kanshi
+
+`/home/pi/.config/kanshi/config`:
+
+```
+profile {
+    output DSI-1 enable scale 1.000000 mode 800x1280@60.000 position 0,0 transform 270
+}
+```
+
+The DSI display (800x1280 native portrait) is rotated 270 degrees to landscape (1280x800).
+
+### Touchscreen Mapping — labwc
+
+`/home/pi/.config/labwc/rc.xml`:
+
+```xml
+<touch deviceName="10-005d Goodix Capacitive TouchScreen" mapToOutput="DSI-1" mouseEmulation="no"/>
+```
+
+The Goodix capacitive touchscreen is mapped to DSI-1 output with mouse emulation disabled.
+
+### labwc Theme
+
+- Theme: **PiXonyx** (dark variant)
+- Font: **Nunito Sans Light 12** (both active and inactive windows)
+- Title bar colors: `#76747C` background, `#F6F5F4` text
+
+### Panel — wf-panel-pi
+
+`/home/pi/.config/wf-panel-pi/wf-panel-pi.ini`:
+
+```ini
+[panel]
+position=top
+icon_size=32
+window-list_max_width=200
+monitor=DSI-1
+```
+
+### labwc Environment
+
+`/home/pi/.config/labwc/environment`:
+
+```
+XKB_DEFAULT_MODEL=pc105
+XKB_DEFAULT_LAYOUT=us
+XCURSOR_SIZE=24
+```
+
+### GTK Theme
+
+- GTK3: `Breeze`
+- GTK2: (default — `.gtkrc-2.0` is mostly empty)
+- dconf `gtk-theme`: `Breeze`
+- dconf `font-name`: `Nunito Sans Light 12`
+- dconf `cursor-size`: `24`
+
+---
+
+## 5. Plymouth Boot Splash
+
+- **Active theme:** `custom`
+- **Theme path:** `/usr/share/plymouth/themes/custom/`
+- **Splash image:** `splash.png` (210 KB)
+- **Script:** `custom.script` — scales `splash.png` to fit screen while maintaining aspect ratio; only shows during boot (not shutdown)
+
+---
+
+## 6. Chromium Kiosk Setup
+
+### Autostart
+
+`/home/pi/.config/autostart/chromium-kiosk.desktop`:
+
+```ini
+[Desktop Entry]
+Type=Application
+Name=Chromium Fullscreen
+Exec=/home/pi/start-chromium.sh
+```
+
+### Launcher Script
+
+`/home/pi/start-chromium.sh` — key behaviour:
+
+1. Sets `GDK_BACKEND=x11` and unsets `WAYLAND_DISPLAY` (forces X11 via XWayland)
+2. Waits for the desktop environment (pcmanfm/lxsession/xfdesktop) to appear
+3. Launches Chromium with:
+   - `--start-fullscreen --noerrdialogs --disable-infobars`
+   - `--disable-session-crashed-bubble --disable-restore-session-state`
+   - `--no-first-run --password-store=basic --use-mock-keychain`
+   - `--ozone-platform=x11`
+   - `--app=http://127.0.0.1:8080` (GNSS Guard web dashboard)
+4. After launch, uses `wmctrl` to force the window fullscreen
+
+### Chromium Version
+
+`chromium 143.0.7499.169` (Debian trixie + RPi patches)
+
+---
+
+## 7. GNSS Guard Application
+
+### Service
+
+`/etc/systemd/system/gnss-guard.service`:
+
+```ini
+[Service]
+Type=simple
+User=pi
+WorkingDirectory=/home/pi/tm-gnss-guard
+ExecStart=/home/pi/tm-gnss-guard/.venv/bin/python /home/pi/tm-gnss-guard/main.py
+Restart=always
+RestartSec=10
+```
+
+- Runs as user `pi`, restarts on failure.
+- Logs to `/home/pi/tm-gnss-guard/gnss_guard.log` (currently ~207 MB).
+
+### Configuration (`.env.prod`)
+
+| Setting | Value |
+|---------|-------|
+| **Asset name** | `OFFICE_LAB` |
+| **Iteration period** | 30 seconds |
+| **Stale threshold** | 60 seconds |
+| **Validation threshold** | 200 meters |
+| **TM AIS GPS** | Enabled — `https://localhost:8443/location` |
+| **Starlink GPS** | Enabled — `10.130.60.70:9200` |
+| **NMEA Primary** | Enabled — `10.130.60.61:4001` |
+| **NMEA Secondary** | Enabled — `10.130.60.61:4002` |
+| **Web dashboard** | Enabled — `0.0.0.0:8080` |
+| **Demo mode** | `true` |
+| **Server sync** | Enabled — `https://gnss.tototheo.com` |
+| **DB path** | `data/gnss_guard.db` |
+
+### Python Dependencies
+
+```
+grpcio, grpcio-tools, protobuf, yagrc, typing-extensions,
+requests, python-dotenv, Flask, pandas, numpy, folium
+```
+
+### Web Dashboard
+
+Listening on port **8080** (all interfaces). Chromium connects to `http://127.0.0.1:8080` in kiosk mode.
+
+---
+
+## 8. Network Configuration
+
+### Interfaces
+
+| Interface | Status | Address | Notes |
+|-----------|--------|---------|-------|
+| `eth0` | UP | `10.20.50.147/24` | DHCP, default route via `10.20.50.1` |
+| `wlan0` | DOWN | — | WiFi available but not connected |
+| `can0` | DOWN | — | CAN bus interface (reTerminal DM hardware) |
+
+### NetworkManager
+
+Manages networking. Two saved WiFi connections:
+
+1. **RUT_C56F_2G** — WPA-PSK, `wlan0`
+2. **iPhone Shulm** — WPA-PSK, `wlan0`
+
+### DNS
+
+`10.130.60.1` (via NetworkManager/DHCP)
+
+### DHCP Client
+
+`dhcpcd` config is present but NetworkManager is the active manager.
+
+---
+
+## 9. SSH Configuration
+
+- OpenSSH server enabled (`ssh.service`)
+- Standard config: `KbdInteractiveAuthentication no`, `UsePAM yes`, `X11Forwarding yes`
+- `regenerate_ssh_host_keys.service` enabled (cloud-init key regen)
+
+---
+
+## 10. VNC (WayVNC)
+
+- **wayvnc.service** — enabled and running
+- **wayvnc-control.service** — enabled and running
+- Listening on port **5900** (all interfaces)
+- Runs as user `vnc` with GPU acceleration (`--gpu`)
+- Uses Wayland native VNC (no X11 dependency)
+
+---
+
+## 11. Cloud-Init
+
+- Cloud-init is **installed and enabled** (all 5 stages: local, network, config, main, final)
+- Status: `done`
+- `/boot/firmware/user-data` contains the default template (all commented out, no active config)
+
+---
+
+## 12. Hardware & Peripherals
+
+### I2C Devices (bus 1)
+
+| Address | Status |
+|---------|--------|
+| `0x18` | In use (UU) |
+| `0x21` | In use (UU) |
+| `0x29` | In use (UU) |
+
+### USB Devices
+
+| Device | Description |
+|--------|-------------|
+| USB Hub | Microchip 2514 (x2, chained) |
+| Serial | QinHeng CH34x USB Dual Serial |
+
+### Kernel Modules (notable)
+
+| Module | Purpose |
+|--------|---------|
+| `goodix_ts` | Capacitive touchscreen driver |
+| `imx219` | Camera module driver |
+| `mcp251xfd` | CAN bus controller (SPI) |
+| `ch34x` | USB-to-serial converter |
+| `brcmfmac` | Broadcom WiFi |
+| `hci_uart` | Bluetooth UART |
+| `spidev` | SPI userspace interface |
+
+### Serial Ports
+
+- `/dev/ttyS0` — hardware UART (enabled via `enable_uart=1`)
+
+### DRM Devices
+
+- `card0`, `card1` — GPU outputs
+- `renderD128` — GPU render node
+
+---
+
+## 13. Other Installed Software
+
+| Package | Purpose |
+|---------|---------|
+| `maliit-keyboard` | On-screen virtual keyboard (Wayland-native) |
+| `wmctrl` | X11 window manipulation (used by Chromium launcher) |
+| `wlr-randr` | Wayland output configuration tool |
+| `swaybg` | Wayland wallpaper setter |
+| `xinput` | X input device configuration |
+| `libgtk-layer-shell0` | GTK layer-shell support (for overlay windows) |
+| `python3-gi` / `python3-gi-cairo` | Python GObject Introspection bindings |
+| `plasma-browser-integration` | KDE Plasma ↔ Chromium integration |
+| `wayvnc` | Wayland-native VNC server |
+| `autotouch` | Automatic touchscreen association for labwc |
+
+---
+
+## 14. Additional Files in Home Directory
+
+| File/Dir | Purpose |
+|----------|---------|
+| `start-chromium.sh` | Chromium kiosk launcher (see section 6) |
+| `revert-to-lxde.sh` | Script to switch back to LXDE desktop |
+| `auto-fit-page.js` | JS helper for page fitting (likely Chromium extension) |
+| `auto-scale-page.js` | JS helper for page scaling |
+| `tm-gnss-guard/` | GNSS Guard application (see section 7) |
+| `buzzer/` | Buzzer test scripts (`test_buzzer.py`, `test_buzzer.sh`) |
+| `desktop-backup/` | Backup of previous desktop session config |
+| `os_backup/` | OS backup related files |
+
+---
+
+## 15. Services Summary
+
+### Custom / Non-Default Enabled Services
+
+| Service | Description |
+|---------|-------------|
+| `gnss-guard.service` | TM GNSS Guard — GPS monitoring (custom) |
+| `lightdm.service` | Display manager with auto-login |
+| `wayvnc.service` | VNC server for remote access |
+| `wayvnc-control.service` | VNC control companion service |
+| `cloud-init (5 units)` | Cloud-init first-boot provisioning |
+| `ModemManager.service` | Modem management |
+| `NetworkManager.service` | Network management |
+| `bluetooth.service` | Bluetooth |
+| `ssh.service` | SSH server |
+| `cups.service` | Printing (probably not needed for kiosk) |
+| `nfs-blkmap.service` | NFS block mapping (probably not needed) |
+| `rpcbind.service` | RPC port mapper (probably not needed) |
+| `smartmontools.service` | Disk SMART monitoring |
+
+### Listening Ports
+
+| Port | Service | Binding |
+|------|---------|---------|
+| 22 | SSH | `0.0.0.0` |
+| 631 | CUPS | `127.0.0.1` |
+| 1716 | KDE Connect | `*` |
+| 5900 | WayVNC | `*` |
+| 8080 | GNSS Guard web | `0.0.0.0` |
+
+---
+
+## 16. Key Differences from Automated Provisioning
+
+Comparing to the current `first-boot.conf`, this backup image has:
+
+1. **Hostname:** Still `raspberrypi` — the automated flow sets it to `guard`
+2. **Desktop session:** Using `rpd-labwc` (same as automated target)
+3. **Chromium launcher:** Manual script at `/home/pi/start-chromium.sh` using X11/XWayland, while the automated flow uses a Wayland-native approach
+4. **Display rotation:** Configured via kanshi (same 270 degree rotation)
+5. **Touchscreen:** Mapped in labwc `rc.xml` (same Goodix → DSI-1 mapping)
+6. **Plymouth:** Custom theme installed manually
+7. **GNSS Guard:** Deployed from separate repo, running as systemd service
+8. **Theme:** labwc PiXonyx + GTK Breeze (mixed); automated flow uses PiXnoir
+9. **WiFi regulatory:** Set to CY (Cyprus) in cmdline.txt
+10. **CUPS / NFS / rpcbind:** Installed but likely unnecessary for kiosk deployment
--- a/emmc-provisioning/docs/DEVICE-REMOVABLE-PACKAGES.md
+++ b/emmc-provisioning/docs/DEVICE-REMOVABLE-PACKAGES.md
@@ -0,0 +1,281 @@
+# Installed packages — candidates for removal (reTerminal kiosk)
+
+Device: **10.20.50.147** (backup image).  
+Goal: shrink the image by removing apps and services not needed for a Chromium kiosk.
+
+**Keep:** Chromium, LightDM, labwc, kanshi, maliit-keyboard, plymouth, openssh, NetworkManager, WayVNC (if you use it), wf-panel-pi, autotouch, wmctrl, wlr-randr, python3-gi, GTK/labwc themes in use.
+
+---
+
+## 1. Printing (CUPS) — **safe to remove** if no printing
+
+| Package | Notes |
+|---------|--------|
+| `cups` | Print server |
+| `cups-browsed` | Browse for network printers |
+| `cups-client` | Command-line print client |
+| `cups-common` | Shared files |
+| `cups-core-drivers` | Core drivers |
+| `cups-daemon` | Daemon |
+| `cups-filters` | Filter stack |
+| `cups-filters-core-drivers` | |
+| `cups-ipp-utils` | IPP utilities |
+| `cups-pk-helper` | PolicyKit helper |
+| `cups-ppdc` | PPD compiler |
+| `cups-server-common` | Server common |
+| `hplip` | HP printer drivers |
+| `hplip-data` | |
+| `ipp-usb` | USB printer support |
+| `ghostscript` | PostScript (used by printing) |
+
+Remove in one go (will pull in dependencies):
+
+```bash
+sudo apt remove --purge cups cups-browsed cups-client cups-common cups-core-drivers cups-daemon cups-filters cups-filters-core-drivers cups-ipp-utils cups-pk-helper cups-ppdc cups-server-common hplip hplip-data ipp-usb ghostscript
+# Then: sudo apt autoremove --purge
+```
+
+---
+
+## 2. NFS / RPC — **safe to remove** if no NFS
+
+| Package | Notes |
+|---------|--------|
+| `nfs-common` (if present) | NFS client |
+| `rpcbind` | RPC port mapper (used by NFS) |
+| `nfs-blkmap` (service) | pNFS block layout |
+
+```bash
+sudo apt remove --purge rpcbind  # and nfs-* if listed by dpkg -l
+sudo systemctl disable nfs-blkmap.service  # if you don't use NFS
+```
+
+---
+
+## 3. Development / build tools — **safe to remove** for kiosk
+
+| Package | Notes |
+|---------|--------|
+| `build-essential` | gcc, g++, make |
+| `gcc` `gcc-14` `g++` `g++-14` | Compilers |
+| `cpp` `cpp-14` | Preprocessor |
+| `make` | Build tool |
+| `gdb` | Debugger |
+| `dpkg-dev` | Package build tools |
+| `binutils` `binutils-aarch64-linux-gnu` | Linker, etc. |
+| `patch` | Patch utility |
+| `git` `git-man` | Version control |
+| `device-tree-compiler` | DTB compiler (only if you don’t build overlays) |
+| `fakeroot` | Build env |
+| `eatmydata` | Speed up builds |
+
+```bash
+sudo apt remove --purge build-essential gcc gcc-14 g++ g++-14 cpp cpp-14 gdb dpkg-dev binutils binutils-aarch64-linux-gnu patch git git-man device-tree-compiler fakeroot eatmydata
+sudo apt autoremove --purge
+```
+
+---
+
+## 4. Office / document viewers — **safe to remove**
+
+| Package | Notes |
+|---------|--------|
+| `evince` `evince-common` | PDF/document viewer |
+| `libevdocument3-4` `libevview3-3` (often pulled by evince) | |
+| `catdoc` | Word document text extraction |
+| `libreoffice-*` (if any) | Office suite |
+
+```bash
+sudo apt remove --purge evince evince-common catdoc
+# If present: sudo apt remove --purge libreoffice-core libreoffice-common ...
+sudo apt autoremove --purge
+```
+
+---
+
+## 5. KDE Plasma apps (many) — **review; remove what you don’t use**
+
+You’re using **labwc** as the session, but a lot of KDE packages are still installed (dolphin, konsole, kate, etc.). Removing big KDE apps can free a lot of space; keep anything your kiosk or panel needs.
+
+**File manager / desktop:**
+- `dolphin` `dolphin-data` `dolphin-doc` `dolphin-plugins`
+- `kde-baseapps`
+- `baloo6` (file indexer)
+
+**Editors / text:**
+- `kate` `kate-data`
+- `kwrite`
+- `mousepad` (XFCE editor)
+
+**Terminal:**
+- `konsole` `konsole-kpart`
+
+**Browser / bookmarks:**
+- `konqueror` `konqueror-data` `konqueror-doc`
+- `keditbookmarks`
+
+**System / config:**
+- `kinfocenter`
+- `khelpcenter` `khelpcenter-data`
+- `ksystemstats`
+- `kfind`
+- `kmenuedit`
+- `kdialog`
+- `kde-cli-tools` `kde-cli-tools-data`
+- `kde-config-screenlocker` (if you don’t use lock screen)
+- `kde-config-sddm` (you use LightDM, not SDDM)
+- `kde-spectacle` (screenshot)
+- `kscreen` (display config; you use kanshi)
+
+**Connectivity / sharing:**
+- `kdeconnect` `kdeconnect-libs`
+- `kdenetwork-filesharing`
+
+**Wallet / accounts:**
+- `kwalletmanager`
+- `kwallet6`
+- `kaccounts-providers`
+
+**Backup:**
+- `kup-backup`
+
+**Other:**
+- `drkonqi` (KDE crash handler)
+- `kactivitymanagerd`
+- `kde-inotify-survey`
+- `kdegraphics-thumbnailers`
+- `ffmpegthumbs`
+- `frameworkintegration6`
+
+Example (remove a block of KDE apps; adjust to what you want to keep):
+
+```bash
+sudo apt remove --purge dolphin dolphin-data dolphin-doc dolphin-plugins kde-baseapps baloo6 kate kate-data kwrite konsole konsole-kpart konqueror konqueror-data konqueror-doc keditbookmarks kinfocenter khelpcenter khelpcenter-data ksystemstats kfind kmenuedit kdialog kde-spectacle kscreen kdeconnect kdeconnect-libs kdenetwork-filesharing kwalletmanager kup-backup drkonqi kactivitymanagerd kde-inotify-survey kdegraphics-thumbnailers ffmpegthumbs
+sudo apt autoremove --purge
+```
+
+**Keep** (likely used by labwc/panel/theme): things like `breeze`, `breeze-gtk-theme`, `kwin-wayland`/`kwin-common` (if labwc or something depends on them), `plasma-browser-integration` if you want Chromium integration.
+
+---
+
+## 6. Image / media tools — **safe to remove** if not needed
+
+| Package | Notes |
+|---------|--------|
+| `eom` `eom-common` | Eye of MATE image viewer |
+| `imagemagick` `imagemagick-7.q16` `imagemagick-7-common` | Image conversion |
+| `gimp` (if present) | Image editor |
+| `grim` | Wayland screenshot (keep only if you use it) |
+
+```bash
+sudo apt remove --purge eom eom-common imagemagick imagemagick-7.q16 imagemagick-7-common
+sudo apt autoremove --purge
+```
+
+---
+
+## 7. Archive / backup tools — **optional**
+
+| Package | Notes |
+|---------|--------|
+| `7zip` | 7z archives |
+| `bup` `bup-doc` | Backup tool |
+| `cryfs` | Encrypted filesystem |
+
+```bash
+sudo apt remove --purge 7zip bup bup-doc cryfs
+sudo apt autoremove --purge
+```
+
+---
+
+## 8. Bluetooth — **optional** (remove if no BT devices)
+
+| Package | Notes |
+|---------|--------|
+| `bluedevil` | KDE Bluetooth |
+| `bluez` `bluez-obexd` `bluez-firmware` | Bluetooth stack |
+
+Removing these will disable Bluetooth. If the kiosk never uses BT:
+
+```bash
+sudo apt remove --purge bluedevil bluez bluez-obexd bluez-firmware
+sudo apt autoremove --purge
+```
+
+---
+
+## 9. Spell-check / dictionaries — **optional**
+
+| Package | Notes |
+|---------|--------|
+| `aspell` `aspell-en` | Spell checker |
+| `hunspell-en-us` `hunspell-en-gb` `hunspell-de-de` `hunspell-fr` `hunspell-fr-classical` `hunspell-nl` | Dictionaries |
+| `hyphen-en-gb` | Hyphenation |
+| `dictionaries-common` | Dictionary config |
+
+```bash
+sudo apt remove --purge aspell aspell-en hunspell-de-de hunspell-en-gb hunspell-en-us hunspell-fr hunspell-fr-classical hunspell-nl hyphen-en-gb dictionaries-common
+sudo apt autoremove --purge
+```
+
+---
+
+## 10. Miscellaneous apps
+
+| Package | Notes |
+|---------|--------|
+| `alacarte` | Menu editor |
+| `galculator` | Calculator |
+| `htop` | Process viewer (keep if you use it for SSH admin) |
+| `arp-scan` | Network scan |
+| `fio` | Disk benchmark |
+| `clinfo` | OpenCL info |
+| `gldriver-test` | GL test |
+| `gui-pkinst` `gui-updater` | GUI package/update tools (RPi) |
+| `partitionmanager` (if present) | Partition editor |
+| `fwupd` `fwupd-arm64-signed` | Firmware updates (optional to keep) |
+| `fprintd` `libpam-fprintd` | Fingerprint (usually not on reTerminal) |
+| `ModemManager` | Modem (remove if no modem) |
+| `evolution-data-server-common` | Evolution PIM (often dependency of others) |
+
+---
+
+## 11. Optional services to disable (not necessarily remove)
+
+- `cups.service` — disable if you removed CUPS
+- `rpcbind.service` — disable if you removed rpcbind
+- `nfs-blkmap.service` — disable if no NFS
+- `bluetooth.service` — disable if you removed Bluetooth
+- `ModemManager.service` — disable if no modem
+
+```bash
+sudo systemctl disable cups.service
+sudo systemctl disable rpcbind.service
+sudo systemctl disable nfs-blkmap.service
+# etc.
+```
+
+---
+
+## Suggested order of removal
+
+1. **Printing:** CUPS + ghostscript + hplip + ipp-usb  
+2. **NFS/RPC:** rpcbind (and nfs-* if present)  
+3. **Development:** build-essential, gcc, g++, git, gdb, etc.  
+4. **Document/office:** evince, catdoc  
+5. **KDE apps:** dolphin, kate, konsole, konqueror, spectacle, kscreen, kdeconnect, etc. (keep what labwc/panel needs)  
+6. **Image/media:** eom, imagemagick  
+7. **Archive/backup:** 7zip, bup, cryfs  
+8. **Bluetooth:** if not needed  
+9. **Spell-check/dictionaries:** if not needed  
+10. **Misc:** alacarte, galculator, fprintd, ModemManager (if not needed)
+
+After each group:
+
+```bash
+sudo apt autoremove --purge
+sudo apt clean
+```
+
+Then re-check with `dpkg -l` and `df -h` to see space saved. If you want a single “remove list” file for scripting, say which categories to include and we can generate one.
--- a/emmc-provisioning/docs/EDIT-CLOUDINIT-ON-DEVICE.md
+++ b/emmc-provisioning/docs/EDIT-CLOUDINIT-ON-DEVICE.md
@@ -0,0 +1,121 @@
+# How to edit cloud-init files on the device before capturing the image
+
+The cloud-init **NoCloud** files live on the **boot partition**. On the running device they are at:
+
+| File | Path on device |
+|------|----------------|
+| **user-data** | `/boot/firmware/user-data` |
+| **meta-data** | `/boot/firmware/meta-data` |
+| **network-config** | `/boot/firmware/network-config` |
+
+They are owned by **root** and need **sudo** to edit.
+
+---
+
+## Method 1: Edit on the device over SSH
+
+1. **SSH into the device** (e.g. via jump host):
+
+   ```bash
+   ssh -o ConnectTimeout=10 -J root@10.20.30.153 pi@10.20.50.147
+   ```
+
+2. **Edit with nano** (or `vi` if you prefer):
+
+   ```bash
+   sudo nano /boot/firmware/user-data
+   sudo nano /boot/firmware/meta-data
+   sudo nano /boot/firmware/network-config
+   ```
+
+3. **Save and exit:** in nano, `Ctrl+O` then Enter to save, `Ctrl+X` to exit.
+
+4. **YAML:** use **spaces only** for indentation (no tabs). Wrong indentation can break cloud-init.
+
+---
+
+## Method 2: Copy to your PC, edit, copy back
+
+1. **Copy from device to your PC** (from your project machine):
+
+   ```bash
+   scp -o ConnectTimeout=10 -J root@10.20.30.153 \
+     pi@10.20.50.147:/boot/firmware/user-data   ./user-data
+   scp -o ConnectTimeout=10 -J root@10.20.30.153 \
+     pi@10.20.50.147:/boot/firmware/meta-data  ./meta-data
+   scp -o ConnectTimeout=10 -J root@10.20.30.153 \
+     pi@10.20.50.147:/boot/firmware/network-config ./network-config
+   ```
+
+   If you get "Permission denied" reading from `/boot/firmware/`, on the device run:  
+   `sudo cp /boot/firmware/user-data /boot/firmware/meta-data /boot/firmware/network-config /tmp/ && sudo chmod 644 /tmp/user-data /tmp/meta-data /tmp/network-config`  
+   then from your PC: `scp -J root@10.20.30.153 pi@10.20.50.147:/tmp/user-data ./user-data` (and same for meta-data, network-config).
+
+2. **Edit** `user-data`, `meta-data`, and `network-config` on your PC.
+
+3. **Copy back** (push from PC to device). Because the destination is root-owned, use a two-step on the device, or use root SSH:
+
+   **Option A – copy to home then move with sudo:**
+
+   ```bash
+   # On your PC: copy to pi's home
+   scp -o ConnectTimeout=10 -J root@10.20.30.153 ./user-data ./meta-data ./network-config \
+     pi@10.20.50.147:~/
+
+   # Then on the device (SSH in as pi):
+   sudo cp ~/user-data ~/meta-data ~/network-config /boot/firmware/
+   sudo chmod 644 /boot/firmware/user-data /boot/firmware/meta-data /boot/firmware/network-config
+   ```
+
+   **Option B – if you have root SSH to the device:**
+
+   ```bash
+   scp -o ConnectTimeout=10 -J root@10.20.30.153 ./user-data root@10.20.50.147:/boot/firmware/
+   scp -o ConnectTimeout=10 -J root@10.20.30.153 ./meta-data root@10.20.50.147:/boot/firmware/
+   scp -o ConnectTimeout=10 -J root@10.20.30.153 ./network-config root@10.20.50.147:/boot/firmware/
+   ```
+
+---
+
+## What to edit (typical)
+
+- **meta-data**  
+  - `instance_id`: change if you want cloud-init to treat this as a new instance (e.g. per device).  
+  - Add `local-hostname: guard` (or your hostname) so the hostname is set on first boot.
+
+- **user-data**  
+  - Uncomment and set `hostname: ...` if you don’t use meta-data hostname.  
+  - To run your **first-boot script** from the provisioning server, add a `runcmd` section that downloads and runs it (see `cloud-init/user-data-remote-gnss.example` in the repo).  
+  - In that runcmd, set the **FILE_SERVER** URL to match your deployment network (e.g. `http://10.20.50.1:5000/files/first-boot` or your LXC IP).
+
+- **network-config**  
+  - Uncomment and adjust if you need static IP or specific WiFi; otherwise DHCP is usually enough.
+
+---
+
+## Example: minimal user-data that runs first-boot from your server
+
+You can replace (or add to) the default template with something like this, and adjust the URL to your file server:
+
+```yaml
+#cloud-config
+package_update: true
+package_upgrade: false
+packages: [curl]
+
+runcmd:
+  - curl -fsSL "http://10.20.50.1:5000/files/first-boot.sh" -o /tmp/first-boot.sh
+  - curl -fsSL "http://10.20.50.1:5000/files/first-boot.conf" -o /tmp/first-boot.conf
+  - chmod +x /tmp/first-boot.sh
+  - /tmp/first-boot.sh
+```
+
+Full example with user, SSH, and optional first-boot config: **emmc-provisioning/cloud-init/user-data-remote-gnss.example**.
+
+---
+
+## After editing
+
+- No reboot needed for the edits to “take effect”; they are just files on the boot partition.  
+- When you **capture the image** (backup), the boot partition is included, so the updated `user-data`, `meta-data`, and `network-config` will be on the golden image.  
+- On **first boot** after deploy, cloud-init reads these files and runs accordingly.
--- a/emmc-provisioning/docs/PREPARE-IMAGE-FOR-CLOUDINIT.md
+++ b/emmc-provisioning/docs/PREPARE-IMAGE-FOR-CLOUDINIT.md
@@ -0,0 +1,72 @@
+# Preparing a backup image for cloud-init (reuse as golden image)
+
+This describes what was done to the **device** (e.g. 10.20.50.147) so the **backup image** you take from it is smaller and suitable for deployment as a **golden image** with cloud-init running on first boot.
+
+---
+
+## 1. Size reductions applied
+
+| Action | Effect |
+|--------|--------|
+| Removed old kernel (6.12.47) and headers | ~130 MB freed; current kernel 6.12.62 kept |
+| APT cache already cleaned | (done earlier) |
+| Logs truncated, journal vacuumed | (done earlier) |
+| KDE/Plasma removed | (done earlier; ~2.6 GB freed) |
+
+**Result:** Root filesystem ~**7.5 GB** used (28% of 29 GB). After taking the backup you can shrink with **PiShrink** (and optionally compress) for storage and faster deploy; see [EMMC-PROVISIONING-GUIDE.md](EMMC-PROVISIONING-GUIDE.md#shrinking-backup-and-golden-images-pishrink).
+
+---
+
+## 2. Cloud-init preparation (so it re-runs after deploy)
+
+These steps were run on the device so that when you **restore this image** to another reTerminal (or the same one after wipe), the next boot is treated as **first boot** and cloud-init runs again.
+
+| Step | What was done |
+|------|----------------|
+| **cloud-init clean** | `cloud-init clean --logs --machine-id --seed` so cloud-init state and seed are removed; next boot is detected as first boot. |
+| **machine-id** | Set to `uninitialized`; systemd will generate a new unique ID on first boot. |
+| **SSH host keys** | Removed from `/etc/ssh/`; `regenerate_ssh_host_keys.service` (or cloud-init) will create new keys on first boot. |
+| **Hostname** | Reset to `raspberrypi` in `/etc/hostname` and `/etc/hosts`; cloud-init can set the real hostname from **meta-data** or **user-data**. |
+
+No reboot was performed on the device so you can take the backup immediately.
+
+---
+
+## 3. Boot partition (NoCloud)
+
+The device already had cloud-init **NoCloud** files on the boot partition:
+
+- `/boot/firmware/user-data`
+- `/boot/firmware/meta-data`
+- `/boot/firmware/network-config`
+
+When you use this backup as **golden image** and deploy it:
+
+1. **Cloud-init** will run on first boot and use these files.
+2. If **user-data** is set up to download and run your **first-boot script** (e.g. from the provisioning portal), ensure:
+   - The **FILE_SERVER** URL in that script (or in `first-boot.conf` on the server) is correct for the deployed network (e.g. `http://10.20.50.1:5000/files/first-boot` or your LXC IP).
+   - The portal has the right **first-boot.conf** and **first-boot** assets (sync with `scripts/sync-portal-files-to-lxc.sh`).
+
+If you prefer different **user-data** / **meta-data** / **network-config** (e.g. different hostname, WiFi, or runcmd), either:
+
+- Edit them **on the device** before taking the backup, or  
+- After copying the image to the host, **mount the boot partition** of the image and replace `user-data`, `meta-data`, and optionally `network-config` with your versions (see [EMMC-PROVISIONING-GUIDE.md](EMMC-PROVISIONING-GUIDE.md)).
+
+---
+
+## 4. Optional: further size reduction
+
+If you need a smaller image:
+
+- **Remove unused locales** (e.g. with `localepurge` or by removing locale packages); can save hundreds of MB.
+- **Remove more packages** (see [DEVICE-REMOVABLE-PACKAGES.md](DEVICE-REMOVABLE-PACKAGES.md)): e.g. CUPS, NFS, development tools, extra fonts.
+- **PiShrink** the backup after imaging (shrinks rootfs and optionally compresses); see the guide above.
+
+---
+
+## 5. Taking the backup
+
+1. Use your normal **Backup** flow (e.g. reTerminal in boot mode → dashboard **Backup**), or `dd`/clone the eMMC to a file.
+2. Optionally run **PiShrink** (and compress) on the host.
+3. Set the result as **golden image** in the dashboard if you want to deploy it to other devices.
+4. On first boot after deploy, cloud-init will run; SSH host keys and machine-id will be new; set hostname and the rest via **user-data** / **meta-data** or your first-boot script.