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
• Google Chrome in kiosk mode - managed by the daemon
• eco-daemon - Deno binary that orchestrates everything
• Management UI on port 3006

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 + Chrome 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 Chrome 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/Chrome 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-chrome.hook.chroot  # Installs Chrome
│   │   │   └── 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
• Chrome app_id rules for fullscreen

Chrome Launch

Command: google-chrome-stable Flags:

• --ozone-platform=wayland
• --kiosk
• --no-first-run
• --disable-infobars
• URL: http://localhost:3006

Port 3006 Management UI

• Serves HTML dashboard
• Shows Sway/Chrome status
• Shows CPU/memory stats
• Shows daemon logs
• WebSocket for live updates

Build Process

Prerequisites

docker  # For isolated build environment

Build Commands

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

chmod +x isobuild/config/hooks/normal/*.hook.chroot

If hooks aren't executable, Chrome won't be installed!

Testing in QEMU

Start Test VM

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

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

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

Chrome Not Starting

1. Check if Chrome is installed: which google-chrome-stable
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
• Chrome: google-chrome-stable from dl.google.com
• Deno: Latest (for daemon compilation)