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

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, Chromium 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

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)