eco_os/readme.hints.md

EcoOS Project Hints

Project Structure

eco_os/
├── ecoos_daemon/       # Daemon source code (Deno/TypeScript)
├── isobuild/           # ISO build configuration (Dockerfile, hooks, includes)
├── isotest/            # Test scripts (run-test.sh, screenshot.sh, stop.sh)
└── .nogit/             # Generated files (not in git)
    ├── iso/            # Built ISO (ecoos.iso)
    ├── vm/             # QEMU files (disk, sockets, logs)
    └── screenshots/    # VM screenshots

Build & Test Commands (package.json)

# Build ISO (auto-rebuilds daemon first)
pnpm run build

# Test ISO in QEMU
pnpm run test

# Take screenshot
pnpm run test:screenshot

# Stop QEMU VM
pnpm run test:stop

# Clean build artifacts
pnpm run clean

# Daemon development (watch mode)
pnpm run daemon:dev

# Bundle daemon to binary
pnpm run daemon:bundle

Current Network Configuration

Using systemd-networkd (NOT NetworkManager) with DHCP:

• Config file: /etc/systemd/network/10-wired.network
• Matches: ens*, enp*, eth*
• Uses DHCP (QEMU user networking provides DHCP)

The installer (install.sh) creates this config explicitly during installation.

Browser: Chromium (not Firefox, not Google Chrome)

The project uses Chromium for the kiosk browser.

Key Files

• isobuild/config/hooks/normal/0060-install-chromium.hook.chroot - Installs Chromium dependencies
• ecoos_daemon/ts/daemon/process-manager.ts - Launches Chromium with Wayland support

Why Chromium from Debian?

Ubuntu 24.04 made chromium-browser snap-only. Snap doesn't work in live-build chroot environments. The hook adds Debian sid repo temporarily to install the real Chromium package.

Sway Configuration

Sway config is generated dynamically by the daemon at runtime, NOT from a static file.

The daemon writes the config to ~/.config/sway/config before starting Sway with -c flag.

Chromium Kiosk Flags

--ozone-platform=wayland
--kiosk
--no-first-run
--disable-infobars
--disable-session-crashed-bubble
--disable-restore-session-state

Chromium app_id on Wayland

Chromium identifies as chromium-browser or Chromium-browser in Sway.

eco-daemon Binary

The binary at isobuild/config/includes.chroot/opt/eco/bin/eco-daemon is compiled from ecoos_daemon/ using Deno.

Note: pnpm run build automatically rebuilds the daemon before building the ISO.

ISO Boot Menu

1. Install EcoOS (auto-selects in 10s) - Default
2. EcoOS Live (Try without installing)
3. EcoOS Live (Safe Mode)

CRITICAL: Sway + QEMU Display Fix

ISSUE: Sway shows gray/black screen with windows not rendering properly in QEMU.

FIX: In isotest/run-test.sh, use -vga qxl instead of -device virtio-vga

Source: ArchWiki Sway page, GitHub issue swaywm/sway#6210

CRITICAL: Hook Permissions

ISSUE: Chromium not installed in ISO.

FIX: All hook files must be chmod +x:

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

If hooks aren't executable, live-build SKIPS them silently!

Serial Console Debugging

Use socat to connect to QEMU serial console:

socat - UNIX-CONNECT:.nogit/vm/serial.sock

Login: ecouser/ecouser, then sudo -i for root.

Lesson: ALWAYS RESEARCH BEFORE FIXING

When encountering issues:

1. DO NOT assume the same fix will work repeatedly
2. DO research the issue online first
3. Check ArchWiki, GitHub issues, official docs
4. Understand WHY the fix works
5. Document findings in readme.hints.md

Testing Protocol

• Take screenshots every 10 seconds during testing, NOT 45+ seconds
• Use serial console for debugging network/service issues
• Check ip addr on guest to verify network interface has IP