archy/AUTOBOOT_CONFIGURATION.md

# Archipelago Auto-Boot Configuration

## Overview

The Archipelago OS is configured to automatically:
1. ✅ Connect to internet via Ethernet (DHCP)
2. ✅ Start the Archipelago backend server
3. ✅ Serve the web UI on port 8100

## Boot Sequence

### 1. System Init (sysinit level)
- Hardware detection
- Device filesystem setup
- Kernel modules loading

### 2. Boot Services (boot level)
```
00-boot-services.start → Configures all boot services
  ├── networking    → Network stack initialization
  ├── hostname      → Set hostname to "archipelago-node"
  ├── syslog        → System logging
  └── hwclock       → Hardware clock sync
```

### 3. Network Configuration (boot level)
```
01-network-setup.start → Automatic network configuration
  ├── Configure /etc/network/interfaces (DHCP)
  ├── Start networking service
  ├── Wait for IP address assignment
  ├── Configure DNS (Google/Cloudflare)
  ├── Test internet connectivity
  └── Display access information
```

**Ethernet Interfaces Supported:**
- `eth0` - Standard Ethernet
- `enp0s3` - VirtualBox/VMware
- `enp0s25` - Intel Ethernet (HP ProDesk)
- `ens0` - Modern naming convention

**Network Configuration:**
- DHCP automatic IP assignment
- DNS: 8.8.8.8, 8.8.4.4, 1.1.1.1
- Hostname: archipelago-node

### 4. Default Services (default level)
```
archipelago service → Main backend server
  ├── Waits for network to be ready
  ├── Creates data directories
  ├── Starts Rust backend on port 8100
  ├── Serves Vue.js UI
  └── Manages container orchestration
```

**Service Configuration:**
- User: `archipelago` (unprivileged)
- Port: `8100` (HTTP)
- Data: `/var/lib/archipelago/`
- Logs: `/var/lib/archipelago/logs/`
- Auto-restart on failure

### 5. Hardware Detection
```
00-hardware-detect.start → Hardware optimization
  ├── Detect CPU vendor and model
  ├── Detect RAM capacity
  ├── Detect storage devices (NVMe/SATA)
  ├── Load appropriate drivers
  ├── Apply hardware-specific optimizations
  └── Log to /var/log/archipelago-hardware.log
```

## Service Files

### OpenRC Init Script
**Location:** `/etc/init.d/archipelago`

```sh
#!/sbin/openrc-run
name="Archipelago"
command="/usr/bin/archipelago-backend"
command_user="archipelago:archipelago"

depend() {
    need net           # Requires network
    need localmount    # Requires filesystems
    use podman docker  # Uses containers if available
}
```

**Features:**
- Waits for network to be ready (pings 8.8.8.8)
- Creates required directories
- Sets proper permissions
- Displays access URL on start

### Network Configuration
**Location:** `/etc/network/interfaces`

```
auto eth0
iface eth0 inet dhcp
    hostname archipelago-node
```

**Features:**
- Automatic DHCP configuration
- Multiple interface support
- Hostname broadcast

### Server Configuration
**Location:** `/etc/archipelago/config.toml`

```toml
[server]
host = "0.0.0.0"  # Listen on all interfaces
port = 8100

[network]
auto_configure = true
dhcp = true
dns_servers = ["8.8.8.8", "8.8.4.4", "1.1.1.1"]

[ui]
enabled = true
path = "/usr/share/archipelago/web"
```

## First Boot Experience

### What Happens

1. **System boots** from USB or internal drive
2. **Network starts** automatically
   - DHCP requests IP address
   - Waits up to 30 seconds for network
   - Tests connectivity (ping 8.8.8.8)
3. **Hardware detected**
   - CPU, RAM, storage identified
   - Optimizations applied
4. **Archipelago starts**
   - Backend server launches
   - UI becomes available
   - Containers ready

### Console Output

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🏝️  Archipelago Bitcoin Node OS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Network Configuration:
  IP Address: 192.168.1.100/24

Access the Archipelago UI at:
  http://192.168.1.100:8100

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

## Accessing the UI

### From Local Network

1. **Find the IP address:**
   - Check router's DHCP leases
   - Look for "archipelago-node"
   - Or check console output on first boot

2. **Open browser:**
   ```
   http://192.168.1.100:8100
   ```
   (Replace with your device's IP)

3. **Access the UI:**
   - No login required on first boot
   - Configure system
   - Install apps

### From Same Machine

If you have a monitor and keyboard connected:

```
http://localhost:8100
```

## Troubleshooting

### No Network Connection

**Check network status:**
```bash
# Check if interface is up
ip addr show

# Check routing
ip route show

# Test connectivity
ping -c 4 8.8.8.8

# Restart networking
rc-service networking restart
```

### Service Not Starting

**Check service status:**
```bash
# Check if service is enabled
rc-status

# Start service manually
rc-service archipelago start

# View logs
tail -f /var/lib/archipelago/logs/archipelago.log

# Check system logs
dmesg | grep -i archipelago
```

### Can't Access UI

**Check server is running:**
```bash
# Check if port is listening
netstat -tlnp | grep 8100

# Check process
ps aux | grep archipelago

# Test locally
curl http://localhost:8100
```

## Manual Configuration

### Set Static IP (Optional)

Edit `/etc/network/interfaces`:

```
auto eth0
iface eth0 inet static
    address 192.168.1.100
    netmask 255.255.255.0
    gateway 192.168.1.1
    hostname archipelago-node
```

Then restart networking:
```bash
rc-service networking restart
```

### Change Server Port

Edit `/etc/archipelago/config.toml`:

```toml
[server]
port = 8080  # Change to desired port
```

Then restart service:
```bash
rc-service archipelago restart
```

### Enable SSH Access

SSH is enabled by default. Connect with:

```bash
ssh archipelago@192.168.1.100
```

Default credentials will be set during first boot.

## Security Notes

### First Boot
- Authentication disabled for initial setup
- All network interfaces accessible
- HTTP only (no HTTPS yet)

### After Setup
- Enable authentication in config
- Set strong passwords
- Consider firewall rules
- Enable HTTPS (optional)

## Service Management

### Start/Stop/Restart

```bash
# Start service
rc-service archipelago start

# Stop service
rc-service archipelago stop

# Restart service
rc-service archipelago restart

# Check status
rc-service archipelago status
```

### Enable/Disable Auto-Start

```bash
# Enable auto-start
rc-update add archipelago default

# Disable auto-start
rc-update del archipelago default

# List all services
rc-update show
```

## File Locations

### Configuration
- `/etc/archipelago/config.toml` - Main config
- `/etc/archipelago/hardware.toml` - Hardware profile
- `/etc/network/interfaces` - Network config

### Data
- `/var/lib/archipelago/` - Main data directory
- `/var/lib/archipelago/apps/` - App data
- `/var/lib/archipelago/secrets/` - Encrypted secrets
- `/var/lib/archipelago/logs/` - Log files

### Binaries
- `/usr/bin/archipelago-backend` - Backend server
- `/usr/share/archipelago/web/` - UI files

### Logs
- `/var/log/archipelago-hardware.log` - Hardware detection
- `/var/lib/archipelago/logs/` - Service logs

## Summary

✅ **Automatic Ethernet Connection**
- DHCP configuration
- Multiple interface support
- DNS auto-configuration
- Internet connectivity test

✅ **Automatic Server Start**
- Backend launches on boot
- Waits for network readiness
- Auto-restarts on failure
- Proper user permissions

✅ **Accessible Web UI**
- Available on port 8100
- Accessible from local network
- No setup required
- Ready to use immediately

**Your Archipelago node is fully automated and ready to run! 🏝️**