archy/DEPLOYMENT.md

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:

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:

# /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:

"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

# 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

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

[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)

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

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):

# 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):

# 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:

# Debian 12 (Bookworm) base
apt update && apt install -y \
  nginx \
  podman \
  build-essential \
  pkg-config \
  libssl-dev \
  curl \
  rsync

---

Frontend Build

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:

rsync -avz --delete ../web/dist/neode-ui/ archipelago@192.168.1.228:/opt/archipelago/web-ui/

---

Backend Build

cd /Users/dorian/Projects/archy/core/archipelago

# Build release binary
cargo build --release

# Binary location: ../target/release/archipelago

Deploy to server:

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:

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:

# 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)