lfg2025/archy
1
0
Fork 0
Code Issues 25 Pull Requests 4 Actions Packages Projects Releases 74 Wiki Activity

Update .gitignore and remove obsolete documentation files

Browse Source 
- Added new entries to .gitignore for build artifacts and macOS output directories to streamline the build process.
- Deleted outdated documentation files: AUTH_LOGIN_FIX.md, AUTBOOT_CONFIGURATION.md, BACKEND_FIXES.md, BACKEND_STARTUP_FIX.md, BITCOIN_CORE_HEADLESS_FIX.md, BITCOIN_CORE_UI_COMPLETE.md, BITCOIN_STANDALONE_UI_COMPLETE.md, BITCOIN_UI_COMPLETE.md, BOOT_SEQUENCE_DIAGRAM.txt, and BUILD_COMMANDS_REFERENCE.txt to declutter the repository and remove unnecessary content.
This commit is contained in:
Dorian
2026-02-01 02:22:02 +00:00
parent 8f0b080e73
commit c9722a34f6
143 changed files with 2036 additions and 17839 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+17 -16
View File
@@ -2,16 +2,16 @@
## Overview
Archipelago is a next-generation Bitcoin Node OS built on Alpine Linux with Podman containerization, combining the modularity of Parmanode with the security and efficiency of a minimal server OS.
Archipelago is a next-generation Bitcoin Node OS built on Debian Linux with Podman containerization, combining the modularity of Parmanode with the security and reliability of a proven server OS. Similar to StartOS, we use Debian Live for reliable USB boot and installation.
## System Architecture
```
┌─────────────────────────────────────────────────────────┐
│ Alpine Linux Base (130MB) │
│ - Minimal kernel │
│ - Hardened security │
│ - Read-only root filesystem │
│ Debian Linux Base (Bookworm) │
│ - Stable, well-supported kernel │
│ - Systemd service management │
│ - Extensive hardware support │
└─────────────────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
@@ -25,10 +25,10 @@ Archipelago is a next-generation Bitcoin Node OS built on Alpine Linux with Podm
│
┌───────────▼───────────┐
│ Container Orchestration│
│ Layer (new) │
│ Layer │
│ - Manifest parser │
│ - Podman client │
│ - Dependency resolver │
│ - Dependency resolver │
│ - Health monitor │
└───────────┬───────────┘
│
@@ -45,10 +45,11 @@ Archipelago is a next-generation Bitcoin Node OS built on Alpine Linux with Podm
## Key Components
### 1. Alpine Linux Base
### 1. Debian Linux Base
- **Size**: ~130MB (vs 1.5GB+ for Umbrel/StartOS)
- **Security**: Hardened kernel, minimal attack surface
- **Distribution**: Debian 12 (Bookworm) - stable, LTS support
- **Init System**: Systemd for service management
- **Security**: AppArmor, standard Debian hardening
- **Multi-arch**: ARM64 (Raspberry Pi) and x86_64 support
### 2. Container Orchestration Layer
@@ -61,7 +62,7 @@ Located in `core/container/`:
### 3. Backend API Extensions
New RPC endpoints in `core/startos/src/container/`:
New RPC endpoints in `core/archipelago/src/container/`:
- `container-install`: Install app from manifest
- `container-start/stop/remove`: Container lifecycle
- `container-status/logs`: Status and debugging
@@ -94,7 +95,7 @@ Located in `core/parmanode/`:
### 7. Security Modules
Located in `core/security/`:
- **container_policies.rs**: Generates AppArmor/SELinux profiles
- **container_policies.rs**: Generates AppArmor profiles
- **secrets_manager.rs**: Encrypted secrets storage
- **image_verifier.rs**: Cosign signature verification
@@ -102,7 +103,7 @@ Located in `core/security/`:
Located in `core/performance/`:
- **resource_manager.rs**: CPU/memory/disk allocation
- **optimize-alpine.sh**: OS-level optimizations
- **optimize-debian.sh**: OS-level optimizations
## App Categories
@@ -134,12 +135,12 @@ Located in `core/performance/`:
## Security Model
1. **OS Level**: Hardened Alpine, read-only root, minimal kernel
1. **OS Level**: Debian hardening, AppArmor, minimal installed packages
2. **Container Level**: Rootless Podman, capability dropping, network isolation
3. **Secrets**: Encrypted storage, runtime injection only
4. **Supply Chain**: Signed images (Cosign), SBOM generation
5. **Network**: Firewall, rate limiting, Tor integration
6. **Audit**: Immutable logs, configuration tracking
5. **Network**: Firewall (nftables/iptables), rate limiting, Tor integration
6. **Audit**: Journald logging, configuration tracking
## Networking
docs/building-os-images.md
+75 -178
View File
@@ -1,64 +1,54 @@
# Building Archipelago OS Images
This guide explains how to build bootable Alpine Linux OS images for Archipelago Bitcoin Node OS that can be flashed to x86_64 desktop computers (Dell Optiplex, HP ProDesk 400 G4 DM, etc.).
This guide explains how to build bootable Debian Linux OS images for Archipelago Bitcoin Node OS that can be flashed to x86_64 desktop computers (Dell OptiPlex, HP ProDesk 400 G4 DM, Start9 Server Pure, etc.).
## Overview
The build system creates bootable ISO or disk images containing:
- Alpine Linux base system
The build system creates bootable ISO images containing:
- Debian Linux 12 (Bookworm) base system
- Podman container runtime
- Archipelago backend (Rust)
- Archipelago frontend (Vue.js)
- Systemd services
- Network configuration
- Network configuration via NetworkManager
## Prerequisites
### macOS
- **Docker Desktop**: [Install Docker Desktop](https://www.docker.com/products/docker-desktop)
- **xorriso**: `brew install xorriso`
- **7zip**: `brew install p7zip`
- **Disk Space**: At least 10GB free
- **Memory**: 8GB+ recommended
### Linux (HP ProDesk 400 G4 DM)
### Linux
- **Alpine Linux** (preferred) or any Linux with Docker
- **Build Tools**: See installation below
- **Docker** (optional, for building backend)
- **xorriso**: `apt-get install xorriso`
- **7zip**: `apt-get install p7zip-full`
- **Disk Space**: At least 10GB free
## Quick Start
### On macOS
```bash
cd image-recipe
./build-macos.sh
./build-debian-iso.sh
```
This will:
1. Build Docker container with all tools
2. Compile backend and frontend
3. Create Alpine image with Archipelago
4. Output ISO to `results/` directory
1. Download Debian Live ISO (if not cached)
2. Extract and customize the ISO
3. Add Archipelago components
4. Create final bootable ISO
### On Linux
```bash
cd image-recipe
./build-linux.sh
```
For native Alpine Linux:
```bash
cd image-recipe
./build-alpine-native.sh
```
Output: `results/archipelago-debian-12-x86_64.iso`
## Build Process
### Step 1: Build Backend
### Step 1: Build Backend (Optional)
The backend is compiled from Rust source:
If you have local changes to the backend:
```bash
./scripts/build-backend.sh
@@ -67,9 +57,9 @@ The backend is compiled from Rust source:
This creates:
- `build/backend/archipelago` - Compiled binary
### Step 2: Build Frontend
### Step 2: Build Frontend (Optional)
The frontend is built from Vue.js source:
If you have local changes to the frontend:
```bash
./scripts/build-frontend.sh
@@ -78,137 +68,87 @@ The frontend is built from Vue.js source:
This creates:
- `build/frontend/` - Static files
### Step 3: Create APK Package
Backend is packaged as Alpine APK:
### Step 3: Build OS Image
```bash
./scripts/create-backend-apk.sh
./build-debian-iso.sh
```
This creates:
- `apks/archipelago-backend-*.apk`
## Flashing to USB
### Step 4: Build OS Image
The main build script orchestrates everything:
### Using dd (Recommended)
```bash
./build-alpine-iso.sh
```
# macOS
./write-usb-dd.sh /dev/diskN
Or build specific type:
# Or manually:
sudo dd if=results/archipelago-debian-12-x86_64.iso of=/dev/rdiskX bs=4m status=progress
```
```bash
BUILD_TYPE=iso ./build-alpine-iso.sh
BUILD_TYPE=disk ./build-alpine-iso.sh
# Linux
sudo dd if=results/archipelago-debian-12-x86_64.iso of=/dev/sdX bs=4M status=progress
```
## Build Types
### Using Balena Etcher
### ISO Image
Creates a bootable ISO file suitable for:
- Burning to DVD
- Writing to USB drive
- Booting in virtual machines
```bash
BUILD_TYPE=iso ./build-alpine-iso.sh
```
Output: `results/archipelago-0.1.0-x86_64.iso`
### Disk Image
Creates a raw disk image suitable for:
- Direct flashing to SSD/HDD
- Using with `dd` command
- Virtual machine disk
```bash
BUILD_TYPE=disk ./build-alpine-iso.sh
```
Output: `results/archipelago-0.1.0-x86_64.img`
## Flashing to Device
### Using ISO (USB Boot)
1. **Write ISO to USB**:
```bash
# macOS
sudo dd if=results/archipelago-0.1.0-x86_64.iso of=/dev/rdiskX bs=1m
# Linux
sudo dd if=results/archipelago-0.1.0-x86_64.iso of=/dev/sdX bs=1M
```
2. **Boot from USB** on target device
3. **Install to disk** (if installer included) or run live
### Using Disk Image (Direct Flash)
1. **Connect target disk** to build machine
2. **Flash image**:
```bash
# macOS
sudo dd if=results/archipelago-0.1.0-x86_64.img of=/dev/rdiskX bs=1m
# Linux
sudo dd if=results/archipelago-0.1.0-x86_64.img of=/dev/sdX bs=1M
```
3. **Boot from disk** on target device
1. Download [Balena Etcher](https://www.balena.io/etcher/)
2. Select the ISO file
3. Select target USB drive
4. Click Flash
⚠️ **Warning**: Double-check the device path! Flashing to wrong device will destroy data.
## Installation Methods
### 1. Live USB Boot
Boot from the USB to run Archipelago in live mode:
- Test the system without installing
- Changes don't persist after reboot
### 2. Full Disk Installation
From the live environment:
```bash
sudo /archipelago/install-to-disk.sh
```
This will:
1. Partition the target disk (GPT with EFI)
2. Install Debian via debootstrap
3. Install Archipelago components
4. Configure bootloader (GRUB)
## Default Credentials
### Live Mode
- Username: `user`
- Password: `live`
### After Installation
- Username: `archipelago`
- Password: `archipelago`
⚠️ **Change passwords immediately after installation!**
## Customization
### Environment Variables
```bash
# Version
ARCHIPELAGO_VERSION=0.1.0
# Alpine version
ALPINE_VERSION=3.19
# Debian version
DEBIAN_VERSION=bookworm
# Architecture
ARCH=x86_64
# Build type
BUILD_TYPE=iso # or "disk"
ARCH=amd64
# Output directory
OUTPUT_DIR=./results
```
### Custom Profile
Edit `alpine-profile/mkimg.archipelago.sh` to:
- Add/remove packages
- Change kernel options
- Modify boot configuration
### Overlay Files
Add files to `alpine-profile/overlay/` to include in image:
- Configuration files
- Scripts
- Service files
## Build Output
After successful build, you'll find:
```
results/
├── archipelago-0.1.0-x86_64.iso # Bootable ISO
└── archipelago-0.1.0-x86_64.img # Disk image (if disk build)
```
## Troubleshooting
### Docker Issues (macOS)
@@ -246,17 +186,10 @@ cd neode-ui
npm install
```
**Problem**: Alpine aports clone fails
```bash
# Manual clone
cd image-recipe
git clone https://gitlab.alpinelinux.org/alpine/aports.git
```
### Image Boot Issues
**Problem**: Image doesn't boot
- Verify ISO/image integrity
- Verify ISO integrity
- Check BIOS/UEFI settings
- Ensure correct architecture (x86_64)
- Try different boot mode (UEFI vs Legacy)
@@ -266,42 +199,6 @@ git clone https://gitlab.alpinelinux.org/alpine/aports.git
- Verify network: `ip addr`
- Check Podman: `podman info`
## Advanced Usage
### Building on Remote Linux Machine
```bash
# On macOS, copy project
scp -r Archipelago user@linux-machine:/tmp/
# SSH to Linux machine
ssh user@linux-machine
# Build
cd /tmp/Archipelago/image-recipe
./build-linux.sh
```
### Cross-Compilation
For building on different architecture:
```bash
# Install cross-compilation tools
apk add cross-x86_64-linux-musl
# Build with target
cargo build --release --target x86_64-unknown-linux-musl
```
### Custom Kernel
To use custom kernel options:
1. Edit `alpine-profile/mkimg.archipelago.sh`
2. Modify `kernel_flavors` or `kernel_addons`
3. Rebuild image
## Next Steps
After building and flashing:
@@ -314,6 +211,6 @@ After building and flashing:
## Resources
- [Alpine Linux mkimage Documentation](https://wiki.alpinelinux.org/wiki/How_to_make_a_custom_ISO_image)
- [Debian Live Manual](https://live-team.pages.debian.net/live-manual/)
- [Archipelago Architecture](./architecture.md)
- [Development Setup](./development-setup.md)