The z99-archipelago-installer.sh heredoc used $'\033[...]' ANSI-C
quoting inside an unquoted <<PROFILE heredoc. Bash misparses this
during expansion, treating multi-line content as a single ANSI-C
quoted string.
Fix: switch to <<'PROFILE' (quoted, no expansion) and use raw
\033 escape codes in echo -e instead of $'...' variables.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
UEFI boot fix:
- Write proper EFI grub.cfg with root UUID after update-grub
(was missing — GRUB dropped to grub> prompt because it couldn't
find its config on the EFI FAT partition)
Installer TUI (Claude Code-inspired):
- Step counter [1/7] through [7/7] with clean progress display
- Helper functions: step(), ok(), warn(), fail(), spinner()
- Centered output with cc() helper
- Clean status messages instead of emoji + raw echo
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- OnboardingDone: "Go to Login" → "Set Password" with context text
- Reboot: lazy-unmount live FS before USB removal prompt, suppress
kernel SquashFS messages, auto-reboot after 10s countdown
- Initramfs: filter "Possible missing firmware" warnings (cosmetic)
- ISOLINUX: menu centered at bottom (VSHIFT 18, HSHIFT 32, WIDTH 18)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Critical fixes from ISO testing on .198:
- Backend auto-creates default user (password123) on first start
so login works immediately after onboarding
- Force reboot (reboot -f) after install to avoid SquashFS errors
when live USB is removed
- Eject USB before prompting user, not after
- Add firmware-misc-nonfree for Intel i915 GPU (suppresses dozens
of "Possible missing firmware" warnings during initramfs update)
- First boot screen: wait up to 10s for DHCP before showing IP
- First boot screen: compact layout fits 80-col terminals
- ISOLINUX menu resolution dropped to 640x480 for universal
VESA compatibility (was 1024x768, caused scaling on some hardware)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
UEFI (#5): grub-mkstandalone embedded config now insmod's all needed
modules (iso9660, search_label, normal, linux) and uses 'normal' to
load the full grub.cfg. Previous config couldn't find the ISO root.
ISOLINUX (#6, #7): Switch from menu.c32 to vesamenu.c32 for background
image support. Copies splash.png from branding. TIMEOUT 0 for instant
boot (no keyboard lag, no menu flicker). Dark theme with transparent
background over the splash image.
Also: added vesamenu.c32 and libcom32.c32 to build artifacts.
Removed console=ttyS0 from quiet boot (interferes with Plymouth).
Added splash to quiet boot kernel params.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two critical issues found on fresh .198 install:
1. Podman broken — uidmap package missing from rootfs because
--no-install-recommends dropped it. Without newuidmap, rootless
Podman can't create user namespaces. Also add slirp4netns and
fuse-overlayfs which are required for rootless networking and
storage.
2. Tor hidden service dirs created with 750 permissions (setgid).
Tor requires exactly 700. Added explicit mkdir + chmod 700 for
all hidden service dirs before starting Tor.
Both issues fixed on .198 live. Build script updated for future installs.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- sudo not installed in minbase squashfs — caused "command not found"
when pressing Enter to install. We're already root via auto-login.
- ISOLINUX timeout from 5s to 1s — reduces menu flicker/duplication
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Three fixes from real hardware testing:
1. Installer auto-start: replace systemd service with profile.d script.
The service and getty raced on tty1 — service output was overwritten
by the login prompt. Profile.d runs AFTER auto-login, same approach
the working Debian Live build used.
2. xorriso: revert from -append_partition to embedded -e boot/grub/efi.img.
The appended partition approach produces cyl-align-off with zero CHS
geometry, which is why BIOS wouldn't recognize the USB. The embedded
approach matches the working main ISO (cyl-align-on, proper CHS).
3. ISOLINUX: dark theme instead of ugly blue. Black background, orange
title, dark selection highlight. No blue boxes.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Root cause of USB boot failure: our xorriso used -e boot/grub/efi.img
to embed the EFI image inside the ISO. This works for CD-ROM and QEMU
but NOT for USB on real UEFI hardware.
Fix: use the Will Haley / Debian live-build approach:
- -append_partition 2 (GPT type EFI) appends efi.img AFTER ISO data
- -e --interval:appended_partition_2:all:: references the appended partition
- --mbr-force-bootable forces MBR active flag
- grub-mkstandalone with embedded bootstrap config (searches for grub.cfg)
- grub.cfg placed in both /boot/grub/ AND /EFI/BOOT/ on ISO
- grub.cfg uses search --label ARCHIPELAGO to find the ISO root
This is the exact approach used by StartOS, TAILS, and every production
custom Debian live ISO that boots from USB.
Also: iso-debug, iso-branding skills + reference docs, dev-start.sh
option 0 for branding dev, improved dev-branding.sh and test-iso-qemu.sh.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Boot fix:
- Ship proven Debian Live MBR (4552) as branding/isohdpfx.bin — the
ISOLINUX package MBR (33ed) doesn't boot on all hardware. This was
the root cause of "machine doesn't pick up the USB".
Branding:
- Custom GRUB background: pixel-art floating island (1024x574)
- Archipelago pixel-art logo for Plymouth boot splash
- GRUB theme: dark background, orange selected item, no broken font refs
- Plymouth theme: script-based with progress bar, LUKS prompt support
- Plymouth + splash added to target rootfs packages
- GRUB theme installed on both installer ISO and target system
- Serial console (ttyS0) added to kernel params for QEMU debugging
CI improvements:
- Smoke test step: mounts ISO, verifies all critical files, checks
initrd has live-boot, confirms boot=live in grub.cfg. Fails build
before copying to Builds if any check fails.
Dev workflow:
- dev-branding.sh: extract ISO, swap branding, repackage, boot in QEMU
(~10 seconds vs 20 min full rebuild)
- generate-grub-background.py: procedural cyberpunk background generator
- generate-plymouth-logo.py: procedural logo generator
- Improved test-iso-qemu.sh: --bios/--nographic flags, serial logging
Build:
- Simplified live-boot install (clean chroot, no complex fallbacks)
- Static branding images preferred, generators as fallback
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The old Debian Live ISO used -partition_offset 16 which reserves space
for a GPT partition table in the hybrid MBR layout. UEFI firmware on
some machines requires this to recognize the USB as bootable. We
removed it thinking it was Debian Live-specific but it's actually an
xorriso hybrid boot requirement.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The verification used [ -d ] but live-boot-initramfs-tools installs
scripts/live as a regular file, not a directory. Changed to [ -e ].
The chroot install was actually succeeding — only the check was wrong.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The chroot /installer command fails inside the CI container because
the container exits after debootstrap completes (set -e + container
boundary). The chroot then runs on the host where /installer doesn't
exist.
Fix: use apt-get with Dir overrides first, fall back to dpkg-deb -x
extraction of live-boot .deb files directly into the installer root.
This bypasses chroot entirely and is more robust in container-in-
container environments.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two boot fixes:
- live-boot package must be installed via chroot apt-get, not debootstrap
--include (minbase resolver can't handle its deps). Verified initrd was
missing scripts/live* entirely.
- Remove -partition_offset 16 from xorriso — it was designed for the
original Debian Live MBR, not the standard ISOLINUX isohdpfx.bin.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The first ISO build didn't boot. Three root causes:
1. No squashfs-as-root mechanism — the custom initramfs hook mounted
boot media but had no way to use the squashfs as the root filesystem.
Fix: add live-boot + live-boot-initramfs-tools to debootstrap includes.
This is ~100KB and provides proven squashfs-as-root with overlayfs.
2. Broken initramfs — update-initramfs needs /proc, /sys, /dev mounted
in the chroot to detect modules and generate a working initrd.
Fix: bind-mount virtual filesystems before update-initramfs.
3. Missing kernel parameters — GRUB and ISOLINUX configs lacked
boot=live components, so live-boot never activated.
Fix: add boot=live components to all kernel command lines.
Also: add all_video/efi_gop/efi_uga modules to GRUB EFI image for
display output on real hardware, and update installer wrapper to
check /run/live/medium first (where live-boot mounts the ISO).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Major ISO build overhaul on dev-iso branch:
- Replace ~800MB Debian Live download with debootstrap --variant=minbase
(~150MB installer squashfs built from scratch)
- Custom initramfs with archipelago-mount hook for boot media detection
- Systemd service auto-starts installer (replaces profile.d hack)
- GRUB + ISOLINUX configs written from scratch (no Debian Live dependency)
- EFI boot image built with grub-mkimage (no more MBR extraction)
- Archipelago GRUB theme: dark background, Bitcoin orange accents
- Theme installed on both installer ISO and target system
- Rootfs optimizations: --no-install-recommends, strip docs/man/locales,
remove firmware-misc-nonfree/wget/htop, add explicit font deps
- Separate CI workflow (build-iso-dev.yml) for dev-iso branch
- Includes pre-existing fixes from main (build-iso.yml, middleware, Login)
Target: sub-2GB unbundled ISO (down from 3.9GB)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
FileBrowser crash fix:
- Add --cap-add=NET_BIND_SERVICE (port 80 needs it with --cap-drop=ALL)
- Add --cap-add=DAC_OVERRIDE for rootless volume access
- Both in first-boot script and backend config.rs
Test script fixes:
- Extract csrf_token cookie and send as X-CSRF-Token header on RPC calls
- Add --phase1-only flag for safe install-only checks (no side effects)
- Auto-test service uses --phase1-only so it doesn't steal onboarding
Install fixes:
- Pre-create ~/.local/share/containers (ReadWritePaths mount namespace error)
- Fix console-setup.service: add After=tmp.mount + ExecStartPre mkdir /tmp
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds archipelago-post-install-tests.service — runs once after all
services are up, outputs to console + journal + log file at
/var/log/archipelago-post-install-tests.log. Tests password setup,
onboarding, and container lifecycle. Runs with default password
(password123) for automated validation.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- ISO build: configure insecure registry for root podman so FileBrowser
image can be pulled during build (was failing with HTTPS error)
- Auto-login on tty1 so no password prompt on console
- RootRedirect: persistent debug logging to sessionStorage
(view in DevTools > Application > Session Storage > archipelago_boot_log)
- Logs: health check, onboarding state, routing decisions, 401 handling
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Kiosk: show cursor when active (removed -nocursor from Xorg),
unclutter hides after 3s idle. X11 on VT7 for Ctrl+Alt+F1/F7 switching.
- Kiosk: keep getty@tty1 running so MOTD is accessible via Ctrl+Alt+F1
- Kiosk: disable Chromium password save overlay (--password-store=basic)
- Esc: don't navigate back from top-level pages (dashboard, login, kiosk)
to prevent dead-end at root redirect
- PWA: suppress install prompt in kiosk mode (/kiosk path)
- Gamepad: Enter in text fields moves focus to next element (submit button)
instead of submitting the form
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Installer: tee all output to /var/log/archipelago-install.log
on the target disk for post-install debugging
- First boot: oneshot service captures system state 30s after boot:
services, nginx, LUKS, EFI, SSL, containers, journal errors
- On-demand: sudo archipelago-diagnostics to re-run anytime
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
CI build report: checks rootfs contents (nginx, SSL, keyboard, kiosk,
lid config, backend, frontend) and ISO contents after build. Reports
in the Actions log so build issues are immediately visible.
First-boot diagnostics: one-shot systemd service runs 30s after first
boot, logs service status, nginx test, SSL certs, LUKS, podman,
kiosk, console-setup, disk, network, and journal errors to
/var/log/archipelago-first-boot-diag.log. Only runs once (ConditionPathExists).
SSH in and cat the log to debug any fresh install issues.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Preseed keyboard-configuration and console-setup debconf values
to prevent console-setup.service failure on boot
- Enable archipelago-kiosk.service by default on fresh installs
so the system boots into the web UI display, not a login prompt
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Shim-signed package hooks reinstall shimx64.efi and BOOTX64.CSV
which cause 'Failed to open \EFI\BOOT\' with garbled filenames.
Purge the package before grub-install, then nuke everything from
EFI/BOOT except BOOTX64.EFI and grub.cfg.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The live installer environment doesn't have dm_mod loaded, causing
'Cannot initialize device-mapper' during LUKS2 encryption. Also
bind-mount /proc and /sys into chroot so cryptsetup can detect
hardware capabilities.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds logind.conf.d drop-in to HandleLidSwitch=ignore for all
lid close scenarios (battery, external power, docked). Archipelago
nodes installed on laptops won't suspend when the lid is closed.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove the cp to /usr/local/bin that caused 'Text file busy'.
The ISO build script now accepts ARCHIPELAGO_BIN env var to find
the freshly built binary instead of requiring it installed.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
All container image references now pull from 80.71.235.15:3000/archipelago/
instead of Docker Hub and ghcr.io. image-versions.sh is the single source
of truth; all scripts use $*_IMAGE variables instead of hardcoded refs.
Files updated:
- scripts/image-versions.sh: central ARCHY_REGISTRY variable
- core/*/config.rs: registry whitelist includes app registry
- core/*/stacks.rs: Immich + Penpot stack images
- scripts/{first-boot,deploy-to-target,container-specs}.sh: use variables
- docker/*/Dockerfile: nginx base image from registry
- image-recipe/: ISO build, podman config, menu script
- scripts/{container-doctor,deploy-bitcoin-knots,fix-indeedhub,validate-app-manifest}.sh
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
All app images now pull from 80.71.235.15:3000/archipelago/
instead of Docker Hub / ghcr.io. Insecure registry config
baked into ISO for fresh installs.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Podman was caching the rootfs Docker layers, meaning firmware packages
and sources.list changes were never picked up on rebuild. Force fresh
build every time since the rootfs tar is the real cache.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The sed commands to modify debian.sources DEB822 format were silently
failing — firmware packages never got installed. Replace the entire
sources config with traditional sources.list that explicitly includes
non-free-firmware component.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The shim (shimx64.efi.signed) was being installed as BOOTX64.EFI but it
tries to load a second-stage binary with a garbled name, causing
"Failed to open \EFI\BOOT\" errors on machines with Secure Boot disabled.
Fix: use grub-install --removable directly (unsigned GRUB as BOOTX64.EFI).
This works on all UEFI hardware. Users with Secure Boot must disable it.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
EFI boot fix:
- Shim needs grub.cfg in same directory to find the root partition
- Create minimal grub.cfg in /EFI/BOOT/ that chains to /boot/grub/grub.cfg
- Preserve unsigned GRUB as fallback for non-Secure-Boot systems
- Copy full chain to both /EFI/BOOT/ and /EFI/archipelago/ paths
- Log EFI directory contents for debugging
Firmware fix:
- DEB822 format sed was wrong — fix Components line replacement
- Add fallback sources.list entry to guarantee non-free-firmware repo
- Ensures firmware-realtek, intel-microcode actually get installed
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- dd zero the 1MB BIOS boot partition before formatting to prevent
kernel FAT-fs bread() errors during boot (sda1 had stale data)
- Add intel-microcode and amd64-microcode packages to suppress
TSC_DEADLINE and similar CPU firmware bug warnings on boot
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Use find instead of hardcoded filename for downloaded ISO detection
(wget may save with redirect filename or partial name)
- Fix color escape codes: use $'\033' syntax instead of '\033' for
reliable ANSI color rendering in installer output
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add firmware-realtek, firmware-iwlwifi, firmware-misc-nonfree to rootfs
(fixes missing r8169 NIC firmware on Dell and other common hardware)
- Enable non-free-firmware repo in rootfs Dockerfile
- Suppress os-prober GRUB warning (GRUB_DISABLE_OS_PROBER=true)
- Auto-eject USB boot media before reboot to prevent re-entering installer
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The ISO build was using Debian 13 (Trixie) as the live installer base
while the rootfs was built from Debian 12 (Bookworm). This caused:
- Debian 13 kernel/hostname/user in the live environment
- Squashfs errors on reboot from live-boot initramfs hooks
Fixes:
- Pin live ISO to Debian 12.10.0 (archive URL)
- Remove live-boot/live-config packages before initramfs regeneration
- Clean out any live-boot initramfs hooks/scripts from installed rootfs
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- F4: Fetch fresh server state after WebSocket reconnect
- F5: Guard message polling timer with auth check, stop on logout
- F6: Remove NIP-07 listener in appLauncher close()
- F7: Initialize audio player once to prevent listener stacking
- S3: Pin all container images to specific versions, create image-versions.sh
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- F1: Guard connectWebSocket against concurrent calls with isWsConnecting flag
- F2: Serialize mesh send operations with sendQueue to prevent fetchMessages races
- F3: Add global Vue error handler with toast notification
- S1: Replace sudo podman with podman across all scripts (rootless Podman)
- S2: Add health-cmd to all 40 container run commands in first-boot-containers.sh
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
