diff --git a/CLAUDE.md b/CLAUDE.md index 7005deba..0b2ba055 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,403 +1,130 @@ -# CLAUDE.md — Archipelago (Archy) Project Guide +# CLAUDE.md — Archipelago (Archy) -## Project Overview +## Overview -Archipelago is a **Bitcoin Node OS** — a bootable, self-sovereign personal server you flash to USB, install on hardware, and manage via a web UI. Similar to Umbrel/Start9/RaspiBlitz but custom-built with production-grade security. +Archipelago is a **Bitcoin Node OS** — bootable, self-sovereign personal server. Flash to USB, install on hardware, manage via web UI. -**Stack**: Rust backend + Vue 3 (Composition API) + TypeScript (strict) + Vite 7 + Tailwind CSS + Pinia + Podman -**Target OS**: Debian 12 (Bookworm) — x86_64 and ARM64 -**Current version**: 0.1.0 +**Stack**: Rust backend + Vue 3 + TypeScript (strict) + Vite 7 + Tailwind + Pinia + Podman on Debian 12 +**Version**: 0.1.0 | **Target**: x86_64 and ARM64 --- -## BETA FREEZE — ACTIVE (2026-03-18) +## Beta Freeze (2026-03-18) -**Goal: Ship a flawless beta that works perfectly on every machine we install it on.** +**Phase 1: Feature Testing (internal) — WE ARE HERE** -We are in **beta stabilization mode**. The current feature set is LOCKED. Every session must push toward this goal. +Feature set is LOCKED. Only: bug fixes, security hardening, ISO build fixes, UI polish, testing. +No new features, no new apps, no new deps, no scope creep. -### Pipeline - -``` -PHASE 1: Feature Testing (internal) ← WE ARE HERE - ↓ Gate: every feature works, bugs fixed, security hardened, ISO verified -PHASE 2: User Testing (real users on real hardware we don't control) - ↓ Gate: user-reported issues resolved, telemetry shows stable fleet -PHASE 3: Beta Live (public release) -``` - -### What IS allowed -- Bug fixes for existing features -- Security hardening and testing -- Beta telemetry / node reporting (TASK-12 — needed for user testing) -- UI/layout rearrangements (moving things around, improving flow) -- Boot screen completion (FEATURE-4 — already in progress) -- Testing all features end-to-end on fresh installs -- Performance and reliability improvements to existing code -- ISO build hardening - -### What is NOT allowed -- New features (watch-only wallet, mesh balance check, etc. are POST-BETA) -- New app integrations -- New backend modules or RPC endpoints (unless fixing existing bugs or beta telemetry) -- New dependencies (unless required for beta infrastructure) -- Scope creep of any kind - -### Status tracking -- **Progress tracker**: `docs/BETA-PROGRESS.md` — updated every session -- **Beta checklist**: `docs/BETA-RELEASE-CHECKLIST.md` — the acceptance criteria -- **Master plan**: `docs/MASTER_PLAN.md` — phased roadmap (Phase 1/2/3) - -### Session protocol -1. Read `docs/BETA-PROGRESS.md` at start of every session -2. Report current phase and status before starting work -3. Work only on current-phase items -4. Update `docs/BETA-PROGRESS.md` at end of every session with what changed +Track: `docs/BETA-PROGRESS.md` | Checklist: `docs/BETA-RELEASE-CHECKLIST.md` --- ## Quick Reference ```bash -# Frontend local dev (mock backend on :5959, Vite on :8100) -cd neode-ui && npm start - -# Deploy to live server (frontend + backend + restart services) -./scripts/deploy-to-target.sh --live - -# Deploy to both servers -./scripts/deploy-to-target.sh --both - -# Frontend build (outputs to web/dist/neode-ui/) -cd neode-ui && npm run build - -# Type-check frontend -cd neode-ui && npm run type-check - -# Rust checks (run on dev server, NOT macOS) -cargo clippy --all-targets --all-features -cargo fmt --all -cargo test --all-features +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) ``` -Dev server: `http://192.168.1.228` | Local frontend: `http://localhost:8100` (password: `password123`) +## Infrastructure + +| What | Where | +|------|-------| +| Dev server | `192.168.1.228` (SSH key: `~/.ssh/archipelago-deploy`) | +| Secondary | `192.168.1.198` | +| Git remote | `git.tx1138.com` (remote name: `tx1138`) | +| App registry | `80.71.235.15:3000/archipelago/` (HTTP, insecure) | +| CI runner | act_runner on .228, workflow: `.gitea/workflows/build-iso.yml` | +| ISO builds | FileBrowser at `http://192.168.1.228:8083` → Builds/ | +| SSH creds | Gitignored `scripts/deploy-config.sh` | +| Web password | `password123` | ## Architecture ``` -Debian 12 (Bookworm) - ├── Podman (rootless containers) - ├── Nginx (port 80 → proxies /rpc/, /ws/, /health to backend) - ├── Rust Backend (core/) — binary on port 5678 - │ ├── core/archipelago/ — Main binary, RPC endpoints - │ ├── core/container/ — PodmanClient, manifest parser, dependency resolver, health monitor - │ ├── core/security/ — AppArmor profiles, secrets manager, Cosign image verifier - │ ├── core/performance/ — Resource manager - │ └── core/parmanode/ — Parmanode compatibility layer +Debian 12 + ├── Podman (rootless, user archipelago) + ├── Nginx (80/443 → backend, app proxies) + ├── Rust Backend (core/) on 127.0.0.1:5678 + │ ├── core/archipelago/ — Binary, RPC, auth, sessions + │ └── core/container/ — PodmanClient, manifests, health └── Vue.js UI (neode-ui/) - ├── src/api/ — RPC client (rpc-client.ts), WebSocket, container client - ├── src/stores/ — Pinia stores - ├── src/views/ — Page components - ├── src/components/ — Reusable components - ├── src/router/ — Vue Router - ├── src/types/ — TypeScript type definitions - └── src/style.css — Global styles + Tailwind utilities + ├── src/api/rpc-client.ts — All backend communication + ├── src/stores/ — Pinia state + ├── src/views/ — Pages + └── src/style.css — ALL styling (global classes only) ``` -### Data Paths (Server) +**Data paths**: `/var/lib/archipelago/{app-id}/` (data), `/opt/archipelago/web-ui/` (frontend), `/usr/local/bin/archipelago` (binary) -- App data: `/var/lib/archipelago/{app-id}/` -- Secrets: `/var/lib/archipelago/secrets/{app-id}/` (encrypted) -- Frontend: `/opt/archipelago/web-ui/` -- Backend binary: `/usr/local/bin/archipelago` -- Systemd service: `/etc/systemd/system/archipelago.service` -- Nginx config: `/etc/nginx/sites-available/archipelago` +## Critical Rules -## CRITICAL Workflow Rules +1. **Never 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, never hardcoded registry paths. +5. **Type-check before committing** — `cd neode-ui && npx vue-tsc -b --noEmit` -### 1. NEVER Build Rust on macOS for Linux +## Frontend -Always rsync source to the Linux dev server and build there. Building on macOS and copying the binary causes Exec format errors. +- `