2026-03-27 12:03:04 +00:00
|
|
|
# CLAUDE.md — Archipelago (Archy)
|
2026-03-04 05:23:42 +00:00
|
|
|
|
2026-03-27 12:03:04 +00:00
|
|
|
Archipelago is a **Bitcoin Node OS** — bootable, self-sovereign personal server. Flash to USB, install on hardware, manage via web UI.
|
2026-03-04 05:23:42 +00:00
|
|
|
|
2026-03-27 12:03:04 +00:00
|
|
|
**Stack**: Rust backend + Vue 3 + TypeScript (strict) + Vite 7 + Tailwind + Pinia + Podman on Debian 12
|
2026-04-02 01:28:11 +01:00
|
|
|
**Version**: 1.3.0 | **Target**: x86_64 and ARM64
|
2026-03-04 05:23:42 +00:00
|
|
|
|
2026-03-27 12:03:04 +00:00
|
|
|
## Beta Freeze (2026-03-18)
|
feat: rootless podman, session hardening, boot stability, sidebar fix
Rootless podman migration (TASK-11):
- Remove sudo from all podman calls in PodmanClient + 8 backend files
- Remove sudo from all podman/docker calls in deploy script
- Restore full systemd security hardening: NoNewPrivileges,
RestrictAddressFamilies, MemoryDenyWriteExecute, RestrictRealtime,
RestrictNamespaces, RestrictSUIDSGID, SystemCallFilter, ProtectSystem=strict
- Enable loginctl linger for rootless container persistence
- Remove Ollama from auto-deploy (marketplace-only)
Session & auth hardening:
- Increase MAX_CONCURRENT_SESSIONS 20→50 (prevents eviction storms)
- Debounced 401 redirect in rpc-client.ts (prevents redirect storms)
Boot stability:
- optimize-debian.sh: adds chrony, swap, removes policy-rc.d
- deploy script: pre-restart chrony + swap setup
- ISO build: chrony package, swap file creation
- BootScreen: no longer clears localStorage (prevents splash replay)
- RootRedirect: sole owner of localStorage clearing on server ready
UI fixes:
- Sidebar opacity default changed from 0→visible (fixes missing sidebar
after page-persistence login without entrance animation)
- Console.log/error wrapped in import.meta.env.DEV guards
- Remove unused route import from RootRedirect
Beta tracking:
- CLAUDE.md: beta freeze protocol added
- MASTER_PLAN.md: TASK-11, TASK-17, phase structure
- BETA-PROGRESS.md: initial tracking doc
- Tagged v1.2.0-alpha.1 as pre-rootless baseline
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-18 13:53:27 +00:00
|
|
|
|
2026-04-08 20:27:38 +02:00
|
|
|
Phase 1: Feature Testing (internal). Feature set is locked.
|
|
|
|
|
Only: bug fixes, security hardening, ISO build fixes, UI polish, testing.
|
2026-03-27 12:03:04 +00:00
|
|
|
Track: `docs/BETA-PROGRESS.md` | Checklist: `docs/BETA-RELEASE-CHECKLIST.md`
|
feat: rootless podman, session hardening, boot stability, sidebar fix
Rootless podman migration (TASK-11):
- Remove sudo from all podman calls in PodmanClient + 8 backend files
- Remove sudo from all podman/docker calls in deploy script
- Restore full systemd security hardening: NoNewPrivileges,
RestrictAddressFamilies, MemoryDenyWriteExecute, RestrictRealtime,
RestrictNamespaces, RestrictSUIDSGID, SystemCallFilter, ProtectSystem=strict
- Enable loginctl linger for rootless container persistence
- Remove Ollama from auto-deploy (marketplace-only)
Session & auth hardening:
- Increase MAX_CONCURRENT_SESSIONS 20→50 (prevents eviction storms)
- Debounced 401 redirect in rpc-client.ts (prevents redirect storms)
Boot stability:
- optimize-debian.sh: adds chrony, swap, removes policy-rc.d
- deploy script: pre-restart chrony + swap setup
- ISO build: chrony package, swap file creation
- BootScreen: no longer clears localStorage (prevents splash replay)
- RootRedirect: sole owner of localStorage clearing on server ready
UI fixes:
- Sidebar opacity default changed from 0→visible (fixes missing sidebar
after page-persistence login without entrance animation)
- Console.log/error wrapped in import.meta.env.DEV guards
- Remove unused route import from RootRedirect
Beta tracking:
- CLAUDE.md: beta freeze protocol added
- MASTER_PLAN.md: TASK-11, TASK-17, phase structure
- BETA-PROGRESS.md: initial tracking doc
- Tagged v1.2.0-alpha.1 as pre-rootless baseline
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-18 13:53:27 +00:00
|
|
|
|
2026-03-04 05:23:42 +00:00
|
|
|
## Quick Reference
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-03-27 12:03:04 +00:00
|
|
|
cd neode-ui && npm start # Local dev (mock backend :5959, Vite :8100)
|
|
|
|
|
cd neode-ui && npm run build # Build (outputs to web/dist/neode-ui/)
|
|
|
|
|
./scripts/deploy-to-target.sh --live # Deploy to live server (.228)
|
2026-03-04 05:23:42 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Architecture
|
|
|
|
|
|
|
|
|
|
```
|
2026-03-27 12:03:04 +00:00
|
|
|
Debian 12
|
|
|
|
|
├── Podman (rootless, user archipelago)
|
|
|
|
|
├── Nginx (80/443 → backend, app proxies)
|
|
|
|
|
├── Rust Backend (core/) on 127.0.0.1:5678
|
2026-03-04 05:23:42 +00:00
|
|
|
└── Vue.js UI (neode-ui/)
|
|
|
|
|
```
|
|
|
|
|
|
2026-03-27 12:03:04 +00:00
|
|
|
**Data paths**: `/var/lib/archipelago/{app-id}/` (data), `/opt/archipelago/web-ui/` (frontend), `/usr/local/bin/archipelago` (binary)
|
2026-03-04 05:23:42 +00:00
|
|
|
|
2026-03-27 12:03:04 +00:00
|
|
|
## Critical Rules
|
2026-03-04 05:23:42 +00:00
|
|
|
|
2026-04-08 20:27:38 +02:00
|
|
|
1. Do not build Rust on macOS — deploy script handles cross-compilation via rsync + remote build.
|
|
|
|
|
2. Always deploy after changes — `./scripts/deploy-to-target.sh --live`
|
|
|
|
|
3. Frontend builds to `web/dist/neode-ui/` — not `neode-ui/dist/`
|
|
|
|
|
4. Container images: `scripts/image-versions.sh` is the single source of truth. All scripts use `$*_IMAGE` variables, not hardcoded registry paths.
|
|
|
|
|
5. Type-check before committing — `cd neode-ui && npx vue-tsc -b --noEmit`
|
2026-03-04 05:23:42 +00:00
|
|
|
|
|
|
|
|
## App Integration Checklist
|
|
|
|
|
|
2026-04-08 20:27:38 +02:00
|
|
|
When adding/fixing apps, check all of these:
|
2026-03-27 12:03:04 +00:00
|
|
|
- `core/archipelago/src/api/rpc/package/` — config, capabilities, deps
|
|
|
|
|
- `neode-ui/src/views/marketplace/marketplaceData.ts` — marketplace entry
|
|
|
|
|
- `image-recipe/configs/nginx-archipelago.conf` — proxy rules (HTTP + HTTPS)
|
|
|
|
|
- `scripts/image-versions.sh` — pinned image version
|
|
|
|
|
- `scripts/first-boot-containers.sh` — first boot creation
|
|
|
|
|
- `scripts/deploy-to-target.sh` — deploy logic
|
2026-03-04 05:23:42 +00:00
|
|
|
|
2026-03-27 12:03:04 +00:00
|
|
|
## Git
|
2026-03-04 05:23:42 +00:00
|
|
|
|
2026-03-27 12:03:04 +00:00
|
|
|
Commits: `type: description` (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`, `perf:`)
|
|
|
|
|
Push to: `git push tx1138 main`
|
2026-04-08 20:27:38 +02:00
|
|
|
|
|
|
|
|
## Compact Instructions
|
|
|
|
|
|
|
|
|
|
When compacting, preserve: list of modified files, test results, deploy target state, current branch, infrastructure IPs.
|