230 lines
6.8 KiB
Markdown
230 lines
6.8 KiB
Markdown
# 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)
|