eco_os/readme.plan.md

# 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)