Revise BUILD-GUIDE and enhance ISO build process
- Updated BUILD-GUIDE.md to streamline instructions for building the Archipelago Auto-Installer ISO, including prerequisites and post-installation steps. - Added detailed sections on capturing the live server state and building from source. - Enhanced Docker and Podman integration in build scripts for improved backend and web UI capture. - Introduced new app metadata for "IndeedHub" in the Docker package scanner and updated UI components for better installation progress tracking. - Improved styling and functionality in the Bitcoin UI for a more cohesive user experience.
This commit is contained in:
Dorian
+417
@@ -0,0 +1,417 @@
|
||||
# Archipelago Deployment & Build Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
This document captures all the critical configurations and fixes needed to build Archipelago from the live development server state.
|
||||
|
||||
**Last Updated:** 2026-02-03
|
||||
**Dev Server:** archipelago@192.168.1.228
|
||||
**Server Disk:** 1.8TB NVMe (1.7TB free)
|
||||
|
||||
---
|
||||
|
||||
## Critical Backend Fixes
|
||||
|
||||
### 1. Podman Container Detection (REQUIRED)
|
||||
|
||||
**Issue:** Backend runs as non-root user but containers are started with `sudo podman` (root context).
|
||||
|
||||
**Fix Applied:** Modified `/core/container/src/podman_client.rs` to use `sudo podman`:
|
||||
|
||||
```rust
|
||||
fn podman_async(&self) -> TokioCommand {
|
||||
// Always use sudo podman to access system-wide containers
|
||||
let mut cmd = TokioCommand::new("sudo");
|
||||
cmd.arg("podman");
|
||||
cmd
|
||||
}
|
||||
```
|
||||
|
||||
**Server Configuration:** Added passwordless sudo for podman:
|
||||
|
||||
```bash
|
||||
# /etc/sudoers.d/archipelago-podman
|
||||
archipelago ALL=(ALL) NOPASSWD: /usr/bin/podman
|
||||
```
|
||||
|
||||
### 2. IndeedHub Metadata in Backend
|
||||
|
||||
**Location:** `/core/archipelago/src/container/docker_packages.rs`
|
||||
|
||||
Added IndeedHub to the `get_app_metadata()` function:
|
||||
|
||||
```rust
|
||||
"indeedhub" => AppMetadata {
|
||||
title: "IndeedHub".to_string(),
|
||||
description: "Decentralized media streaming platform".to_string(),
|
||||
icon: "/assets/img/app-icons/indeedhub.png".to_string(),
|
||||
repo: "https://github.com/indeedhub/indeedhub".to_string(),
|
||||
},
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Nginx Configuration
|
||||
|
||||
### HTTP + HTTPS Setup (with self-signed certs)
|
||||
|
||||
**Location:** `/etc/nginx/sites-available/default`
|
||||
|
||||
```nginx
|
||||
# Redirect HTTP to HTTPS
|
||||
server {
|
||||
listen 80 default_server;
|
||||
listen [::]:80 default_server;
|
||||
server_name _;
|
||||
return 301 https://$host$request_uri;
|
||||
}
|
||||
|
||||
# HTTPS server
|
||||
server {
|
||||
listen 443 ssl http2 default_server;
|
||||
listen [::]:443 ssl http2 default_server;
|
||||
|
||||
ssl_certificate /etc/nginx/ssl/archipelago.crt;
|
||||
ssl_certificate_key /etc/nginx/ssl/archipelago.key;
|
||||
|
||||
ssl_protocols TLSv1.2 TLSv1.3;
|
||||
ssl_ciphers HIGH:!aNULL:!MD5;
|
||||
ssl_prefer_server_ciphers on;
|
||||
|
||||
root /opt/archipelago/web-ui;
|
||||
index index.html;
|
||||
|
||||
server_name _;
|
||||
|
||||
location /rpc/ {
|
||||
proxy_pass http://localhost:5678/rpc/;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_read_timeout 3600s;
|
||||
proxy_send_timeout 3600s;
|
||||
}
|
||||
|
||||
location /ws/ {
|
||||
proxy_pass http://localhost:5678/ws/;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_read_timeout 3600s;
|
||||
proxy_send_timeout 3600s;
|
||||
}
|
||||
|
||||
location /health {
|
||||
proxy_pass http://localhost:5678/health;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
}
|
||||
|
||||
location / {
|
||||
try_files $uri $uri/ /index.html;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### SSL Certificate Generation
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /etc/nginx/ssl
|
||||
sudo openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
|
||||
-keyout /etc/nginx/ssl/archipelago.key \
|
||||
-out /etc/nginx/ssl/archipelago.crt \
|
||||
-subj "/C=US/ST=State/L=City/O=Archipelago/CN=archipelago.local"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Systemd Services
|
||||
|
||||
### Archipelago Backend Service
|
||||
|
||||
**Location:** `/etc/systemd/system/archipelago.service`
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Archipelago Backend
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=archipelago
|
||||
Group=archipelago
|
||||
ExecStart=/usr/local/bin/archipelago
|
||||
Restart=always
|
||||
RestartSec=10
|
||||
Environment="RUST_LOG=debug"
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Container Deployments
|
||||
|
||||
### Bitcoin Knots (Full Node)
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /var/lib/archipelago/bitcoin
|
||||
|
||||
sudo podman run -d \
|
||||
--name bitcoin-knots \
|
||||
--restart unless-stopped \
|
||||
-p 8332:8332 \
|
||||
-p 8333:8333 \
|
||||
-v /var/lib/archipelago/bitcoin:/home/bitcoin/.bitcoin \
|
||||
--label "com.archipelago.app=bitcoin-knots" \
|
||||
--label "com.archipelago.title=Bitcoin Knots" \
|
||||
--label "com.archipelago.version=28.1" \
|
||||
--label "com.archipelago.category=bitcoin" \
|
||||
--label "com.archipelago.description.short=Full Bitcoin node implementation" \
|
||||
--label "com.archipelago.description.long=Bitcoin Knots is a derivative of Bitcoin Core with additional features and bug fixes. Maintain the full blockchain and validate all transactions." \
|
||||
--label "com.archipelago.license=MIT" \
|
||||
--label "com.archipelago.icon=/assets/img/app-icons/bitcoin-knots.webp" \
|
||||
--label "com.archipelago.port=8332" \
|
||||
--label "com.archipelago.repo=https://github.com/bitcoinknots/bitcoin" \
|
||||
docker.io/bitcoinknots/bitcoin:latest \
|
||||
-server=1 \
|
||||
-txindex=1 \
|
||||
-rpcallowip=0.0.0.0/0 \
|
||||
-rpcbind=0.0.0.0:8332 \
|
||||
-rpcuser=archipelago \
|
||||
-rpcpassword=archipelago123 \
|
||||
-dbcache=4096
|
||||
```
|
||||
|
||||
### IndeedHub (Example app deployment)
|
||||
|
||||
See `/Users/dorian/Projects/Indeedhub Prototype/deploy-to-archipelago.sh`
|
||||
|
||||
**Key Requirements:**
|
||||
- Must include `com.archipelago.*` labels for proper detection
|
||||
- Port mapping must be explicit
|
||||
- Restart policy: `unless-stopped`
|
||||
|
||||
---
|
||||
|
||||
## Build Process for Beta Release
|
||||
|
||||
### 1. Capture Live Server State
|
||||
|
||||
```bash
|
||||
cd /Users/dorian/Projects/archy/image-recipe
|
||||
|
||||
# Capture from dev server (default)
|
||||
DEV_SERVER=archipelago@192.168.1.228 ./build-auto-installer-iso.sh
|
||||
|
||||
# Or build from source
|
||||
BUILD_FROM_SOURCE=1 ./build-auto-installer-iso.sh
|
||||
```
|
||||
|
||||
### 2. What Gets Captured
|
||||
|
||||
The auto-installer script captures:
|
||||
|
||||
- **Backend Binary:** `/usr/local/bin/archipelago`
|
||||
- **Frontend Assets:** `/opt/archipelago/web-ui/`
|
||||
- **Nginx Configuration:** `/etc/nginx/sites-available/default`
|
||||
- **SSL Certificates:** `/etc/nginx/ssl/`
|
||||
- **Systemd Service:** `/etc/systemd/system/archipelago.service`
|
||||
- **Sudoers Config:** `/etc/sudoers.d/archipelago-podman`
|
||||
|
||||
**NOTE:** Containers are NOT captured in the ISO - they must be deployed after installation.
|
||||
|
||||
### 3. Critical Auto-Installer Fix
|
||||
|
||||
**Location:** `/image-recipe/build-auto-installer-iso.sh` (line ~850)
|
||||
|
||||
The auto-start script MUST NOT check `[ ! -t 0 ]` (non-interactive check):
|
||||
|
||||
```bash
|
||||
# CORRECT (in z99-archipelago-installer.sh):
|
||||
if [ -n "$INSTALLER_STARTED" ]; then
|
||||
return 0
|
||||
fi
|
||||
|
||||
# WRONG (will fail on auto-login):
|
||||
# if [ -n "$INSTALLER_STARTED" ] || [ ! -t 0 ]; then
|
||||
```
|
||||
|
||||
This was causing the installer to hang at `user@debian:~$` prompt.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies Required on Build Machine
|
||||
|
||||
### For Building ISOs (Mac/Linux):
|
||||
|
||||
```bash
|
||||
# Docker or Podman (for rootfs creation)
|
||||
brew install podman
|
||||
# OR
|
||||
brew install docker
|
||||
|
||||
# ISO creation tools
|
||||
brew install xorriso # Mac
|
||||
# OR
|
||||
apt install xorriso # Linux
|
||||
```
|
||||
|
||||
### For Server Runtime:
|
||||
|
||||
```bash
|
||||
# Debian 12 (Bookworm) base
|
||||
apt update && apt install -y \
|
||||
nginx \
|
||||
podman \
|
||||
build-essential \
|
||||
pkg-config \
|
||||
libssl-dev \
|
||||
curl \
|
||||
rsync
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Frontend Build
|
||||
|
||||
```bash
|
||||
cd /Users/dorian/Projects/archy/neode-ui
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Build for production
|
||||
npm run build
|
||||
|
||||
# Output goes to: ../web/dist/neode-ui/
|
||||
```
|
||||
|
||||
**Deploy to server:**
|
||||
|
||||
```bash
|
||||
rsync -avz --delete ../web/dist/neode-ui/ archipelago@192.168.1.228:/opt/archipelago/web-ui/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Backend Build
|
||||
|
||||
```bash
|
||||
cd /Users/dorian/Projects/archy/core/archipelago
|
||||
|
||||
# Build release binary
|
||||
cargo build --release
|
||||
|
||||
# Binary location: ../target/release/archipelago
|
||||
```
|
||||
|
||||
**Deploy to server:**
|
||||
|
||||
```bash
|
||||
scp ../target/release/archipelago archipelago@192.168.1.228:/tmp/
|
||||
ssh archipelago@192.168.1.228 'sudo systemctl stop archipelago && \
|
||||
sudo mv /tmp/archipelago /usr/local/bin/archipelago && \
|
||||
sudo chmod +x /usr/local/bin/archipelago && \
|
||||
sudo systemctl start archipelago'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist (Pre-Release)
|
||||
|
||||
- [ ] Backend detects all running containers
|
||||
- [ ] Frontend loads and connects to backend WebSocket
|
||||
- [ ] Apps show in "My Apps" with correct status
|
||||
- [ ] App Store shows containers with "Installed" badge
|
||||
- [ ] Bitcoin node is syncing blockchain
|
||||
- [ ] Nginx serves frontend correctly
|
||||
- [ ] RPC/WebSocket proxying works
|
||||
- [ ] Auto-installer ISO boots and installs
|
||||
- [ ] Post-install: System boots to login screen
|
||||
- [ ] Web UI accessible at http://server-ip
|
||||
|
||||
---
|
||||
|
||||
## Known Issues
|
||||
|
||||
### Port 443 Not Binding (Post-Reinstall)
|
||||
|
||||
After fresh install, HTTPS (port 443) may not bind even with correct nginx config. **Workaround:** Use HTTP only initially, investigate nginx/systemd socket issues.
|
||||
|
||||
### Browser HTTPS Auto-Upgrade
|
||||
|
||||
Browsers (especially Brave/Chrome) aggressively upgrade to HTTPS. Users may need to:
|
||||
- Clear site data
|
||||
- Disable "HTTPS-Only Mode"
|
||||
- Use `http://` prefix explicitly
|
||||
|
||||
---
|
||||
|
||||
## File Locations Summary
|
||||
|
||||
| Component | Dev Server Location | ISO Build Captures |
|
||||
|-----------|-------------------|-------------------|
|
||||
| Backend Binary | `/usr/local/bin/archipelago` | ✅ Yes |
|
||||
| Frontend Assets | `/opt/archipelago/web-ui/` | ✅ Yes |
|
||||
| Nginx Config | `/etc/nginx/sites-available/default` | ✅ Yes |
|
||||
| SSL Certs | `/etc/nginx/ssl/` | ✅ Yes |
|
||||
| Systemd Service | `/etc/systemd/system/archipelago.service` | ✅ Yes |
|
||||
| Sudoers | `/etc/sudoers.d/archipelago-podman` | ✅ Yes |
|
||||
| Container Data | `/var/lib/archipelago/` | ❌ No - too large |
|
||||
| Bitcoin Blockchain | `/var/lib/archipelago/bitcoin/` | ❌ No - user downloads |
|
||||
|
||||
---
|
||||
|
||||
## Version Control
|
||||
|
||||
**Important Changes to Track:**
|
||||
|
||||
1. `/core/container/src/podman_client.rs` - sudo podman fix
|
||||
2. `/core/archipelago/src/container/docker_packages.rs` - app metadata
|
||||
3. `/neode-ui/src/utils/dummyApps.ts` - frontend app definitions
|
||||
4. `/image-recipe/build-auto-installer-iso.sh` - auto-start fix
|
||||
|
||||
**Commit before building beta:**
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "Prepare for beta release: podman detection, IndeedHub metadata, auto-installer fixes"
|
||||
git tag v0.1.0-beta.1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Emergency Recovery
|
||||
|
||||
If the backend fails to detect containers:
|
||||
|
||||
```bash
|
||||
# Verify sudoers file exists
|
||||
cat /etc/sudoers.d/archipelago-podman
|
||||
|
||||
# Test manual detection
|
||||
sudo podman ps --format json
|
||||
|
||||
# Check backend logs
|
||||
sudo journalctl -u archipelago -f
|
||||
|
||||
# Restart backend
|
||||
sudo systemctl restart archipelago
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Contact
|
||||
|
||||
Development Server: archipelago@192.168.1.228
|
||||
Password: `archipelago`
|
||||
Web UI: http://192.168.1.228 (or https with self-signed cert warning)
|
||||
Reference in New Issue
Block a user