archy/NEW_OVERLAY_ISO.md

✅ NEW APPROACH: Alpine Overlay ISO (apkovl)

What Changed

Previous method: Modified Alpine ISO contents directly → broke boot process

New method: Use Alpine's apkovl (Alpine Package Overlay) system → proper Alpine boot

How It Works

1. ✅ Base Alpine ISO: Untouched, boots normally
2. ✅ Overlay tarball: archipelago.apkovl.tar.gz on ISO root
3. ✅ Boot parameter: apkovl=/archipelago.apkovl.tar.gz tells Alpine to load it
4. ✅ Auto-extracted: Alpine automatically extracts overlay at boot

What's Included

In the Overlay (59MB):

• Archipelago backend (5.7MB Rust binary)
• Vue.js frontend (web UI)
• 21 app manifests (Bitcoin, Lightning, Web5, etc.)
• Installation script: /root/install-archipelago.sh
• Welcome message: Shows at login

New ISO Details

Location: /Users/dorian/Projects/archy/image-recipe/results/archipelago-3.19-hp-prodesk-uefi-x86_64.iso

Size: 267MB (smaller than before!)

Created: Jan 31, 2026 22:03

Boot support:

• ✅ UEFI
• ✅ Legacy BIOS
• ✅ Hybrid bootable

How to Flash

Method 1: Balena Etcher

1. Open Etcher
2. Select the new ISO
3. Flash to USB

Method 2: Terminal (dd)

diskutil list
diskutil unmountDisk /dev/diskN
sudo dd if=/Users/dorian/Projects/archy/image-recipe/results/archipelago-3.19-hp-prodesk-uefi-x86_64.iso of=/dev/rdiskN bs=1m status=progress
diskutil eject /dev/diskN

Expected Boot Sequence

1. Boot from USB

• F9 → Select "UEFI - General UDISK"
• Alpine boots normally ✅
• Overlay auto-loaded ✅

2. Login Prompt

Welcome to Alpine Linux 3.19

╔═══════════════════════════════════════════════════════════╗
║                                                           ║
║   🏝️  ARCHIPELAGO BITCOIN NODE OS                        ║
║                                                           ║
║   To install to disk, login as root and run:             ║
║                                                           ║
║   # setup-alpine                                          ║
║   # /root/install-archipelago.sh                          ║
║                                                           ║
╚═══════════════════════════════════════════════════════════╝

localhost login: _

3. Login as root

• Username: root
• Password: (just press Enter)

4. Install to Disk

Option A: Quick Install (Recommended)

# Run automated installer
/root/install-archipelago.sh

This will:

• Install all required packages (Podman, nginx, etc.)
• Create archipelago user
• Configure networking (DHCP)
• Set up all services
• Install backend, frontend, and app manifests

Option B: Manual Install

# First, install Alpine to disk
setup-alpine

# Answer the prompts:
# - Keyboard layout: us
# - Hostname: archipelago
# - Network: dhcp
# - Root password: (set one)
# - Timezone: (your timezone)
# - Disk: sda (your internal disk)
# - Mode: sys (install to disk)

# After Alpine is installed, run:
/root/install-archipelago.sh

# Reboot
reboot

5. After Reboot

1. Remove USB drive
2. Login as archipelago / archipelago
3. Change password: passwd
4. Access web UI: http://<your-ip>:8100

Why This Works

Alpine Linux has a built-in overlay system called apkovl for customizing live systems:

1. Preserved boot flow: Base Alpine ISO boots normally
2. Automatic overlay: Alpine detects and loads archipelago.apkovl.tar.gz
3. No manual mounting: Everything just works
4. Standard Alpine: Uses official Alpine mechanisms, not hacks

Troubleshooting

If you still get emergency shell:

1. Type: ls /
2. You should see archipelago.apkovl.tar.gz in the root
3. Type: exit - Alpine should continue booting

If overlay doesn't load:

At the boot prompt, ensure you see:

apkovl=/archipelago.apkovl.tar.gz

To manually load overlay:

cd /
tar xzf archipelago.apkovl.tar.gz
mv archipelago-overlay/* /
/root/install-archipelago.sh

---

This is the proper Alpine Linux way to do it! Flash the new ISO and try booting. 🚀

Technical Details

Overlay Structure:

archipelago.apkovl.tar.gz
└── archipelago-overlay/
    ├── etc/
    │   └── local.d/
    │       └── 00-archipelago-welcome.start
    ├── root/
    │   └── install-archipelago.sh
    ├── usr/
    │   ├── local/bin/
    │   │   └── archipelago
    │   └── share/archipelago/web/
    │       └── (Vue.js files)
    └── var/lib/archipelago/
        └── manifests/
            └── (21 app manifests)

Boot Parameters:

• GRUB: apkovl=/archipelago.apkovl.tar.gz
• Syslinux: apkovl=/archipelago.apkovl.tar.gz

Alpine's initramfs automatically:

1. Detects the boot media
2. Finds archipelago.apkovl.tar.gz
3. Extracts it to / (root)
4. Continues normal boot

This is the official Alpine Linux way to create custom live systems!