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>
155 lines
4.4 KiB
Markdown
155 lines
4.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
./build-debian-iso.sh
|
|
```
|
|
|
|
Expected output:
|
|
- [ ] ISO created in `results/` directory
|
|
- [ ] No build errors
|
|
- [ ] File size reasonable (~500MB - 2GB)
|
|
|
|
### 7. Test in QEMU
|
|
|
|
```bash
|
|
./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)
|
|
|
|
```bash
|
|
./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: _______________
|