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

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