eco_os/readme.hints.md

EcoOS Project Hints

Build & Test Commands (package.json)

# Build the Docker image (do this after config changes)
npm run build:docker

# Build the ISO (requires Docker image)
npm run build

# Test ISO in QEMU
npm run test

# Take screenshot
npm run test:screenshot

# Stop QEMU VM
npm run test:stop

# Clean build artifacts
npm run clean

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

# Start daemon directly
npm run daemon:start

# Bundle daemon to binary
npm 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: Google Chrome (not Firefox)

The project uses Google Chrome for the kiosk browser, NOT Firefox.

Key Files

• isobuild/config/hooks/normal/0060-install-chrome.hook.chroot - Installs Google Chrome
• ecoos_daemon/ts/daemon/process-manager.ts - Launches Chrome with Wayland support

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.

Chrome Kiosk Flags

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

Chrome app_id on Wayland

Chrome identifies as google-chrome or Google-chrome in Sway.

eco-daemon Binary

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

After changing daemon code, rebuild with:

npm run daemon:bundle
cp ecoos_daemon/bundle/eco-daemon isobuild/config/includes.chroot/opt/eco/bin/

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: Chrome 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:isotest/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