initial

2026-01-08 18:33:14 +00:00
commit 51c83f846a
38 changed files with 3876 additions and 0 deletions
--- a/readme.plan.md
+++ b/readme.plan.md
@@ -0,0 +1,229 @@
+# EcoOS - System Documentation
+
+## What Is This?
+
+Custom Ubuntu 24.04 LTS ISO that boots into a kiosk mode with:
+- **Sway** (Wayland compositor) - managed by the daemon
+- **Chromium Browser** in kiosk mode - managed by the daemon
+- **eco-daemon** - Deno binary that orchestrates everything
+- **Management UI** on port 3006
+
+## REQUIREMENT: Sway + Chromium Browser
+
+**The system MUST use Chromium browser, NOT Google Chrome.**
+
+### Challenge
+Ubuntu 24.04 made `chromium-browser` snap-only. Snap doesn't work in live-build chroot environments.
+
+### Solution
+Download Chromium directly from official builds or use Debian's chromium package:
+- Option A: Download from https://download-chromium.appspot.com/ (Linux_x64)
+- Option B: Use Debian's chromium .deb package from sid/unstable
+- Option C: Use ungoogled-chromium from OBS (OpenSUSE Build Service)
+
+The daemon must call `chromium-browser` or `chromium` command.
+
+## CRITICAL: Boot Flow
+
+### GRUB Boot Menu (60s timeout)
+When the ISO boots, GRUB shows:
+1. **"Install EcoOS"** - DEFAULT, auto-selects after 60 seconds
+2. "EcoOS Live" - Try without installing
+3. "EcoOS Live (Safe Mode)"
+
+### Install Mode (`ecoos_install=1`)
+When "Install EcoOS" is selected:
+1. Kernel boots with `ecoos_install=1` parameter
+2. `ecoos-installer.service` runs (has `ConditionKernelCommandLine=ecoos_install=1`)
+3. Installer at `/opt/eco/installer/install.sh` runs interactively on tty1
+4. Installer writes to disk, sets up GRUB bootloader
+5. System reboots
+6. **Now boots from installed disk, NOT the ISO**
+
+### Live Mode (No install)
+When "EcoOS Live" is selected:
+1. Boots into RAM (squashfs)
+2. eco-daemon starts via systemd
+3. Sway + Chromium should start
+4. **No persistent storage** - changes lost on reboot
+
+### After Installation (Normal Boot)
+1. System boots from installed disk
+2. eco-daemon.service starts
+3. Daemon writes Sway config to `~/.config/sway/config`
+4. Daemon starts Sway compositor
+5. Daemon starts Chromium in kiosk mode pointing to localhost:3006
+6. Management UI serves on port 3006
+
+## Architecture
+
+```
+eco_os/
+├── ecoos_daemon/           # Deno daemon source
+│   └── ts/
+│       ├── daemon/
+│       │   ├── index.ts         # Main daemon orchestration
+│       │   ├── process-manager.ts # Sway/Chromium process control
+│       │   └── system-info.ts   # CPU/memory stats
+│       └── ui/
+│           └── server.ts        # HTTP server + WebSocket
+├── isobuild/
+│   ├── Dockerfile              # Docker build environment
+│   ├── config/
+│   │   ├── hooks/normal/       # Chroot hooks (MUST BE EXECUTABLE)
+│   │   │   ├── 0050-setup-ecouser.hook.chroot
+│   │   │   ├── 0055-fix-networkmanager.hook.chroot
+│   │   │   ├── 0060-install-chromium.hook.chroot  # Installs Chromium
+│   │   │   └── 0100-enable-services.hook.chroot
+│   │   ├── includes.chroot/    # Files copied into ISO
+│   │   │   ├── etc/
+│   │   │   │   ├── NetworkManager/system-connections/wired.nmconnection
+│   │   │   │   └── systemd/system/
+│   │   │   │       ├── eco-daemon.service
+│   │   │   │       └── ecoos-installer.service
+│   │   │   └── opt/eco/
+│   │   │       ├── bin/eco-daemon    # Compiled daemon binary
+│   │   │       └── installer/install.sh
+│   │   └── systemd/eco-daemon.service
+│   └── output/                 # Built ISOs
+└── isotest/                    # QEMU test environment
+    ├── run-test.sh
+    ├── test-disk.qcow2         # Persistent test disk
+    └── screenshots/
+```
+
+## Daemon Behavior
+
+### Sway Config Generation
+The daemon **generates Sway config at runtime** - there is NO static config file.
+
+Location: `~/.config/sway/config` (written before Sway starts)
+
+Features:
+- Black background
+- 1920x1080 resolution
+- No window borders
+- All windows forced fullscreen
+- Chromium app_id rules for fullscreen
+
+### Chromium Launch
+Command: `chromium-browser` (or `chromium`)
+Flags:
+- `--ozone-platform=wayland`
+- `--kiosk`
+- `--no-first-run`
+- `--disable-infobars`
+- URL: `http://localhost:3006`
+
+### Port 3006 Management UI
+- Serves HTML dashboard
+- Shows Sway/Chromium status
+- Shows CPU/memory stats
+- Shows daemon logs
+- WebSocket for live updates
+
+## Build Process
+
+### Prerequisites
+```bash
+docker  # For isolated build environment
+```
+
+### Build Commands
+```bash
+# 1. Build Docker image (includes daemon compilation)
+npm run build:docker
+
+# 2. Build ISO (takes ~5-10 minutes)
+npm run build
+
+# ISO output: isobuild/output/ecoos.iso
+```
+
+### IMPORTANT: Hook Permissions
+All files in `isobuild/config/hooks/normal/*.hook.chroot` MUST be executable:
+```bash
+chmod +x isobuild/config/hooks/normal/*.hook.chroot
+```
+
+If hooks aren't executable, Chromium won't be installed!
+
+## Testing in QEMU
+
+### Start Test VM
+```bash
+npm run test
+```
+This:
+- Creates test-disk.qcow2 if needed (20GB)
+- Boots ISO with UEFI
+- Port forwards 3006 and 22
+- Runs headless with VNC on :0
+
+### Access
+- **VNC**: `localhost:5900` (view display)
+- **SSH**: `localhost:2222` (after install, user: ecouser)
+- **Management UI**: `localhost:3006` (after eco-daemon starts)
+
+### Check Progress
+```bash
+# View serial console
+tail -f isotest/serial.log
+
+# Take screenshot
+npm run test:screenshot
+
+# Stop VM
+npm run test:stop
+```
+
+### Fresh Install Test
+To test a fresh installation:
+```bash
+npm run test:stop
+rm isotest/test-disk.qcow2
+npm run test
+# Wait 60s for auto-install, or use VNC to watch
+```
+
+## Network Configuration
+
+### QEMU User Mode Networking
+- VM gets IP via DHCP (usually 10.0.2.15)
+- Port 3006 forwarded: host:3006 -> guest:3006
+- Port 2222 forwarded: host:2222 -> guest:22
+
+### NetworkManager Config
+File: `/etc/NetworkManager/system-connections/wired.nmconnection`
+- Configures wired ethernet with DHCP
+- Permissions fixed by 0055-fix-networkmanager.hook.chroot
+
+## Troubleshooting
+
+### Chromium Not Starting
+1. Check if Chromium is installed: `which chromium-browser`
+2. Check hook permissions: `ls -la isobuild/config/hooks/normal/`
+3. Rebuild Docker image: `npm run build:docker`
+
+### Port 3006 Not Accessible
+1. Check eco-daemon status: `systemctl status eco-daemon`
+2. Check daemon logs: `journalctl -u eco-daemon -f`
+3. Check NetworkManager: `nmcli device status`
+
+### Sway Not Starting
+1. Check seatd: `systemctl status seatd`
+2. Check daemon logs for Sway errors
+3. Verify ecouser exists: `id ecouser`
+
+### Boot Stuck in Live Mode
+- GRUB menu shows for 60 seconds
+- Default option should be "Install EcoOS"
+- Check if `ecoos_install=1` is in kernel cmdline
+
+## Version Info
+
+- Base: Ubuntu 24.04 LTS (Noble)
+- Kernel: 6.8.0-90
+- Sway: From Ubuntu repos
+- Chromium: From Debian sid/unstable or official Chromium builds
+- Deno: Latest (for daemon compilation)