archipelagoandClaude Opus 5
210430967d
The first-boot per-device secret regeneration was fail-open: both branches logged a warning and continued, and `touch "$MARKER"` ran unconditionally outside both `if` blocks. Combined with the unit's ConditionPathExists=! and the script's own marker fast-path, one transient failure left that node on the image-wide shared SSH host key and TLS private key permanently and silently — and the ISO is a published artefact, so every downloader holds those keys. - Retry each generator 3 times with backoff (D-05), so a transient first-boot condition recovers inside the same boot instead of being terminal. - Write the completion marker ONLY when both TLS and SSH succeeded, so a failed boot leaves the unit eligible to run again on the next boot. - On terminal failure: durable record at /var/lib/archipelago/first-boot-secrets.failed naming which generator failed, plus console + logger + stderr, and exit 1 so the unit lands in `failed` rather than `active`. The record is cleared on a later success. - Add FIRST_BOOT_SECRETS_ROOT / FIRST_BOOT_SECRETS_BACKOFF seams. Unset in production the behaviour is byte-identical; set, they let the fail-closed property be asserted rather than claimed. - Order the unit After=systemd-random-seed.service (no-op today, correct if a seed file is ever baked). - State the operational trade in the script header: after the rootfs strip, a terminal failure means no SSH and no TLS and needs the physical console. That was chosen deliberately over running on fleet-shared keys. tests/first-boot-secrets/run-tests.sh extracts the shipped heredoc body from the builder and drives it against a temp root with stubbed generators: both succeed, openssl fails every attempt, ssh-keygen fails twice then succeeds. Moving the marker touch back outside the success branch makes case 2 fail with MARKER-SET-ON-FAILURE, which is the regression this pins. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Archipelago OS Image Recipes
Build scripts for creating bootable Debian Linux OS images for Archipelago Bitcoin Node OS.
Quick Start
Build the ISO
# 1. Sync latest configs from live dev server
./sync-from-live.sh
# 2. Build components
./scripts/build-backend.sh
./scripts/build-frontend.sh
# 3. Build the ISO
./build-debian-iso.sh
This creates a bootable Debian Live ISO with Archipelago pre-installed.
Write to USB
# Using dd (recommended)
./write-usb-dd.sh /dev/diskN
# Or use Balena Etcher to flash the ISO
See the ISO-BUILD-CHECKLIST.md for a comprehensive build workflow.
See the Architecture documentation for detailed system information.
What's Included
- Debian Linux Base: Debian 13 (Trixie) with security updates applied during ISO/install creation
- Podman: Container runtime for apps (rootless by default)
- Archipelago Backend: Rust-based API server
- Archipelago Frontend: Vue.js web interface
- Systemd Services: Automatic service management
- Network Configuration: NetworkManager for easy setup
Build Output
results/archipelago-installer-x86_64.iso- Bootable hybrid ISO image
Supported Platforms
- x86_64: Dell OptiPlex, HP ProDesk 400 G4 DM, Start9 Server Pure, and other x86_64 machines
- Build Systems: macOS (requires Docker) and Linux (native or Docker)
Installation Methods
1. Live USB Boot
Boot from USB, run in live mode to test, or install to disk.
2. Full Disk Installation
From the live environment, run:
sudo /archipelago/install-to-disk.sh
This installs Archipelago to a target disk using debootstrap.
Directory Structure
image-recipe/
├── build-debian-iso.sh # Main ISO builder
├── write-usb-dd.sh # Write ISO to USB with dd
├── create-fat32-usb.sh # Alternative USB creation
├── archipelago-scripts/ # Scripts included in ISO
│ ├── install-to-disk.sh # Disk installer
│ └── setup-bitcoin.sh # Bitcoin Core setup
├── scripts/ # Build helper scripts
│ ├── build-backend.sh # Compile Rust backend
│ ├── build-frontend.sh # Build Vue.js frontend
│ └── check-dependencies.sh # Verify build requirements
└── results/ # Built ISO output
Requirements
- Docker (for macOS builds)
- xorriso (for ISO creation):
brew install xorriso - 7zip (for ISO extraction):
brew install p7zip