archipelagoandClaude Opus 5
6ba0599639
Demo images / Build & push demo images (push) Failing after 2m13s
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>
4.4 KiB
4.4 KiB
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 filesbuild-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 creatingimmich_serverstack - First-boot: Waits for postgres (pg_isready) before starting Immich server
- Backend:
package.installfor 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
rootuser - Check Podman context:
sudo podman psshould 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: _______________