nearxos/reterminal-dm4
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
<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.
This commit is contained in:
nearxos
2026-02-24 00:19:40 +02:00
parent df180120aa
commit 808fbf5c7c
136 changed files with 407837 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
emmc-provisioning/cloud-init/fileserver/bootstrap.sh Normal file
View File

@@ -0,0 +1,4 @@
#!/bin/bash
# Minimal bootstrap script for cloud-init first boot (test).
set -e
echo "[$(date -Iseconds)] test completed" | tee -a /var/log/cloud-init-bootstrap.log

19
emmc-provisioning/cloud-init/fileserver/bootstrap.sh.example Normal file
View File

@@ -0,0 +1,19 @@
#!/bin/bash
# Example bootstrap script run by cloud-init at first boot.
# Copy to bootstrap.sh, edit as needed, and place in your portal files (e.g. first-boot/)
# so it is served at http://YOUR_SERVER:5000/files/bootstrap.sh
#
# Cloud-init downloads this and runs it as root. Add your first-boot logic here:
# - Install packages, apply config, run first-boot.sh from this repo, etc.
set -e
echo "[$(date -Iseconds)] Bootstrap script started."
# Example: run the full first-boot flow from your file server (same as user-data-remote-gnss.example)
# FILE_SERVER="http://10.20.50.1:5000/files/first-boot"
# curl -fsSL "$FILE_SERVER/first-boot.sh" -o /tmp/first-boot.sh
# curl -fsSL "$FILE_SERVER/first-boot.conf" -o /tmp/first-boot.conf
# chmod +x /tmp/first-boot.sh
# /tmp/first-boot.sh
echo "[$(date -Iseconds)] Bootstrap script finished."

7
emmc-provisioning/cloud-init/meta-data.guard Normal file
View File

@@ -0,0 +1,7 @@
# NoCloud meta-data: hostname "guard" and instance id for cloud-init.
# Copy to the boot (FAT32) partition as "meta-data" (same directory as user-data).
# instance-id: guard-01
# Hostname set on first boot
local-hostname: guard

35
emmc-provisioning/cloud-init/user-data.bootstrap Normal file
View File

@@ -0,0 +1,35 @@
#cloud-config
# Minimal user-data: download bootstrap.sh from your file server and run it at first boot.
#
# 1. Host bootstrap.sh at a URL reachable from the device on first boot (e.g. your
# provisioning portal or file server). Example: http://10.20.50.1:5000/files/bootstrap.sh
# 2. Copy this file to the boot partition as "user-data" (with meta-data and optional network-config).
# 3. Edit BOOTSTRAP_URL below to match your server (or set it once in the runcmd section).
package_update: true
package_upgrade: false
packages:
- curl
# Ensure SSH is enabled and password auth allowed so you can log in after first boot
write_files:
- path: /etc/ssh/sshd_config.d/99-cloud-init.conf
content: |
PasswordAuthentication yes
PermitRootLogin no
runcmd:
- systemctl enable ssh
- systemctl start ssh
# Download and run bootstrap script (edit URL to match your file server)
- |
BOOTSTRAP_URL="http://10.20.50.1:5000/files/bootstrap.sh"
LOG="/var/log/cloud-init-bootstrap.log"
if ! curl -fsSL "$BOOTSTRAP_URL" -o /tmp/bootstrap.sh 2>>"$LOG" || [ ! -s /tmp/bootstrap.sh ]; then
echo "$(date -Iseconds) ERROR: Failed to download bootstrap.sh from $BOOTSTRAP_URL (file missing or empty)" >> "$LOG"
exit 0
fi
chmod +x /tmp/bootstrap.sh
/tmp/bootstrap.sh
- cloud-init single --name cc_final_message

4
emmc-provisioning/dashboard/app.py
View File

@@ -1175,8 +1175,8 @@ def api_backups_upload():
def _set_golden_from_path(path):
"""Set golden image to point to given path (file in backups or cloudinit dir)."""
GOLDEN_IMAGE.parent.mkdir(parents=True, exist_ok=True)
if GOLDEN_IMAGE.exists():
GOLDEN_IMAGE.unlink()
# Remove existing file or symlink (including broken symlink; exists() is False for broken links)
GOLDEN_IMAGE.unlink(missing_ok=True)
path_resolved = path.resolve()
try:
path_resolved.relative_to(BACKUPS_DIR.resolve())

451
emmc-provisioning/docs/BACKUP-DEVICE-CONFIG-AUDIT.md Normal file
View File

@@ -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

281
emmc-provisioning/docs/DEVICE-REMOVABLE-PACKAGES.md Normal file
View File

@@ -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.

121
emmc-provisioning/docs/EDIT-CLOUDINIT-ON-DEVICE.md Normal file
View File

@@ -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.

72
emmc-provisioning/docs/PREPARE-IMAGE-FOR-CLOUDINIT.md Normal file
View File

@@ -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.