lfg2025/archy
1
0
Fork 0
Code Issues 27 Pull Requests 4 Actions Packages Projects Releases 74 Wiki Activity
Files
fa14f6ebaad2215d2bdbd5ddcb4d523e38a3e5d4
archy/image-recipe/_archived/ISO-BUILD-CHECKLIST.md
T
archipelagoandClaude Opus 5 6ba0599639
Demo images / Build & push demo images (push) Failing after 2m13s
Details
security: remove all infrastructure and internal process material from the repo 
The repo is source code and guidelines only. Nothing about how Archipelago's
own fleet is run, or how the team works, stays in it.

Untracked (kept on disk, gitignored) — 250 files:
- .planning/ (199) and loop/ — internal development process
- fleet operations tooling that targets specific nodes: deploy-to-target,
  deploy-tailscale, deploy-config-defaults, setup-target-dev, setup-aiui-server,
  setup-https-dev, debug-frontend, node-profile, fleet-fips-pair/unpair,
  image-recipe/sync-from-live.sh
- image-recipe/INTEGRATION-GUIDE.md and docs/multinode-testing-plan.md, both of
  which are live-server workflow and fleet node inventories
- the Phase 10 on-node verification and evidence records, which cite .planning/
  as their evidence base

KEY-05-ENTROPY-ENFORCEMENT.md was initially moved out with the other Phase 10
docs and then put back: it is cited as normative rationale from ten places in
the codebase, including core/clippy.toml, which bans rand::thread_rng and
points at it for the reason. That makes it a guideline, not an internal record.

Node names removed from source (48 occurrences across comments, manifests and
test fixtures): archi-dev-box, archy-x250*, shorty-s, framework-pt,
zaza-optiplex, archi-thinkpad. Comments keep the engineering context and the
date, which is what carried the meaning; the machine name did not.

Three of those were live test values rather than comments and were replaced
with valid stand-ins, not prose: two mDNS hostnames and a mesh peer name.
An earlier pass substituted "a test node" into a hostname assertion, producing
an invalid hostname; caught and fixed as test-node.local.

Wipe mechanism: .local-only/manifest.txt inventories every local-only path and
.local-only/wipe.sh deletes them on one confirmation, refusing to touch
anything git still tracks. Both are themselves untracked, so the public repo
does not carry a map of internal filenames.

Verified: cargo check -p archipelago --all-features clean; archipelago-container
75/75 tests pass; appOrigin vitest 7/7; audit-secrets 5/5; every relative link
in tracked markdown resolves (0 broken).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-07 10:37:20 -04:00

4.4 KiB
Raw Blame History

ISO Build Checklist

This checklist ensures that all changes from the live development server are properly integrated into the ISO build.

Pre-Build Steps

1. Sync System Configurations from Live Server

cd image-recipe

This captures:

  • Systemd service configuration (archipelago.service) - User=root required for Podman
  • Nginx configuration (nginx-archipelago.conf) - includes app proxies (Nextcloud, Vaultwarden, Immich, Penpot)
  • Logrotate configuration (if exists)
  • Any custom scripts in /opt/archipelago/scripts/

Critical: build-auto-installer-iso.sh uses configs/ for nginx and archipelago.service. Ensure these are synced before building.

2. Verify Code Changes

Ensure all code changes are committed:

  • Backend changes in core/
  • Frontend changes in neode-ui/
  • Script changes in scripts/

3. Build Components

cd image-recipe

# Build backend
./scripts/build-backend.sh

# Build frontend  
./scripts/build-frontend.sh

Verify builds:

  • Backend binary exists: build/backend/archipelago
  • Frontend files exist: build/frontend/index.html

Integration Check

4. Update Build Scripts

Review and update if needed:

  • integrate-archipelago.sh - Includes all config files
  • build-debian-iso.sh - Installs to correct paths

5. Critical Configuration Values

Verify in configs/archipelago.service:

  • User=root (required for Podman root context)
  • Environment="ARCHIPELAGO_DEV_MODE=true" (enables container detection)
  • Environment="ARCHIPELAGO_BIND=127.0.0.1:5678"

Verify in configs/nginx-archipelago.conf:

  • Root path: /opt/archipelago/web-ui
  • RPC proxy: /rpc/ → http://127.0.0.1:5678
  • WebSocket proxy: /ws → http://127.0.0.1:5678

Build Process

6. Build the ISO

./build-debian-iso.sh

Expected output:

  • ISO created in results/ directory
  • No build errors
  • File size reasonable (~500MB - 2GB)

7. Test in QEMU

./test-iso-qemu.sh

Test checklist:

  • ISO boots successfully
  • Backend service starts: systemctl status archipelago
  • Nginx serves frontend
  • Can access UI at http://localhost:8080 (or mapped port)
  • Container detection works: Check logs for "Detected container"

App Stack Hardening (Immich, Penpot, etc.)

The first-boot script and deploy script ensure:

  • Immich: Old single-container immich (wrong port) is removed before creating immich_server stack
  • First-boot: Waits for postgres (pg_isready) before starting Immich server
  • Backend: package.install for Immich removes old container before creating stack
  • Deploy: Ensures Immich stack on every deploy, cleans up conflicts

Post-Build

8. Write to USB (Optional)

./write-usb-dd.sh /dev/diskN

Or use Balena Etcher to flash the ISO.

9. Test on Real Hardware

  • Boot from USB
  • Network configuration works
  • All services start automatically
  • Can access web UI
  • Containers are detected and managed

Deployment Paths Reference

The ISO build must install to these paths:

Component Path Source
Backend binary /usr/local/bin/archipelago build/backend/archipelago
Frontend files /opt/archipelago/web-ui/ build/frontend/*
Systemd service /etc/systemd/system/archipelago.service configs/archipelago.service
Nginx config /etc/nginx/sites-available/archipelago configs/nginx-archipelago.conf
Nginx symlink /etc/nginx/sites-enabled/archipelago Link to sites-available

Common Issues

Backend Not Detecting Containers

  • Verify service runs as root user
  • Check Podman context: sudo podman ps should show containers
  • Enable dev mode: ARCHIPELAGO_DEV_MODE=true

UI Not Loading

  • Check nginx configuration paths
  • Verify frontend files deployed to /opt/archipelago/web-ui/
  • Check nginx error logs: /var/log/nginx/error.log

Service Fails to Start

  • Check binary permissions: Should be executable
  • Check systemd logs: journalctl -u archipelago
  • Test binary manually: sudo /usr/local/bin/archipelago

Version Tracking

When building a new ISO, document:

  • Date: _______________
  • Git commit: _______________
  • Backend version: _______________
  • Frontend version: _______________
  • ISO filename: _______________
  • Tested on hardware: _______________
  • Issues found: _______________
Reference in New Issue View Git Blame Copy Permalink