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)
```bash
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)
```bash
# 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
```bash
# 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:
```bash
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!