25ad68ac4c
- BUG-33: CPU load alert threshold increased from 2x to 4x core count (8→16 on 4-core machine) to reduce false alerts during container ops - TASK-27: Launch buttons for new-tab apps now show external link icon (BTCPay, Grafana, PhotoPrism, Portainer, OnlyOffice, etc.) - TASK-36: Iframe error screen now distinguishes between X-Frame-Options blocked vs container not reachable, with appropriate messaging Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
156 lines
5.2 KiB
Markdown
156 lines
5.2 KiB
Markdown
# Archipelago Web UI
|
|
|
|
Vue 3 + TypeScript + Vite + Tailwind CSS + Pinia
|
|
|
|
The web interface for Archipelago — a self-sovereign Bitcoin Node OS.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
cd neode-ui
|
|
npm install
|
|
npm start
|
|
```
|
|
|
|
Visit **http://localhost:8100** — login with password: `password123`
|
|
|
|
This starts:
|
|
- Mock backend on port 5959 (no Docker required)
|
|
- Vite dev server on port 8100 with HMR
|
|
|
|
Stop with `npm stop`.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
neode-ui/
|
|
├── src/
|
|
│ ├── api/ # RPC client (rpc-client.ts), WebSocket, container client
|
|
│ ├── stores/ # Pinia stores (app, container, appLauncher, monitoring)
|
|
│ ├── views/ # Page components (Dashboard, Marketplace, Settings, etc.)
|
|
│ ├── components/ # Reusable components (SplashScreen, AppSession, etc.)
|
|
│ ├── router/ # Vue Router configuration
|
|
│ ├── types/ # TypeScript type definitions
|
|
│ └── style.css # Global styles + Tailwind utilities
|
|
├── public/assets/ # Static assets (images, fonts, app icons, audio)
|
|
├── mock-backend.js # Mock backend server (simulates Rust backend)
|
|
├── docker/ # Docker configs (nginx, entrypoint)
|
|
└── vite.config.ts # Vite config with backend proxy
|
|
```
|
|
|
|
## Dev Modes
|
|
|
|
The mock backend supports multiple startup modes via `VITE_DEV_MODE`:
|
|
|
|
| Mode | Command | Behavior |
|
|
|------|---------|----------|
|
|
| **default** | `npm start` | Fully set up, login screen |
|
|
| **existing** | `VITE_DEV_MODE=existing npm run dev:mock` | Same as default |
|
|
| **setup** | `VITE_DEV_MODE=setup npm run dev:mock` | First-time password setup flow |
|
|
| **onboarding** | `VITE_DEV_MODE=onboarding npm run dev:mock` | Post-setup onboarding flow |
|
|
| **boot** | `npm run dev:boot` | 25s simulated boot sequence |
|
|
|
|
## Mock Backend
|
|
|
|
The mock backend (`mock-backend.js`) simulates the full Rust backend for local development:
|
|
|
|
**Pre-installed apps** (always visible in My Apps):
|
|
- Bitcoin Core, LND, Electrs, Mempool, FileBrowser, LoraBell, ThunderHub, Fedimint
|
|
|
|
**Marketplace**: 30+ curated apps with Docker images, install/uninstall simulation
|
|
|
|
**Features simulated**:
|
|
- Authentication (login, password change, TOTP 2FA)
|
|
- System metrics (CPU, memory, disk — randomized for realism)
|
|
- Node identity (DID, Nostr pubkey, Tor address)
|
|
- Federation (3 mock nodes with apps, metrics, trust levels)
|
|
- Mesh networking (4 LoRa peers, encrypted messaging, invoices)
|
|
- Peer-to-peer messaging
|
|
- FileBrowser API (mock file system with Music, Documents, Photos, Videos)
|
|
- DWN sync status
|
|
- Transport layer (mesh/LAN/Tor routing)
|
|
- Notifications (5 realistic entries)
|
|
- Claude AI chat proxy (requires `ANTHROPIC_API_KEY`)
|
|
|
|
**Container runtime**: If Docker/Podman is available, the mock backend will run real containers for installed apps. Otherwise, it simulates them.
|
|
|
|
## Demo Deployment (Portainer)
|
|
|
|
Deploy the demo via Docker Compose for showcasing:
|
|
|
|
```bash
|
|
docker compose -f docker-compose.demo.yml build
|
|
docker compose -f docker-compose.demo.yml up -d
|
|
```
|
|
|
|
Or deploy through **Portainer Stacks**:
|
|
1. Stacks > Add stack > name: `archy-demo`
|
|
2. Web editor: paste `docker-compose.demo.yml` contents
|
|
3. Add environment variable: `ANTHROPIC_API_KEY` (for Claude chat)
|
|
4. Deploy
|
|
|
|
Access at **http://your-host:4848** — password: `password123`
|
|
|
|
## Development Commands
|
|
|
|
```bash
|
|
npm start # Start mock backend + Vite (recommended)
|
|
npm stop # Stop all servers
|
|
npm run dev:mock # Same as start, without port cleanup
|
|
npm run dev:boot # Boot mode (simulated startup delay)
|
|
npm run backend:mock # Mock backend only
|
|
npm run dev # Vite only (needs backend running separately)
|
|
npm run dev:real # Vite with real Rust backend
|
|
|
|
npm run build # Production build (outputs to ../web/dist/neode-ui/)
|
|
npm run build:docker # Build for Docker (no type checking)
|
|
npm run type-check # TypeScript type checking
|
|
npm test # Run tests
|
|
```
|
|
|
|
## Design System
|
|
|
|
### Glass Classes
|
|
|
|
| Class | Use |
|
|
|-------|-----|
|
|
| `.glass-card` | Content containers, modals, panels |
|
|
| `.glass-button` | ALL buttons (primary and secondary) |
|
|
| `.path-option-card` | Interactive cards with hover lift |
|
|
| `.info-card` | Status badges, metric displays |
|
|
|
|
### Tokens
|
|
|
|
- **Font**: Avenir Next (primary), Montserrat (`font-archipelago`)
|
|
- **Glass**: `bg: rgba(0,0,0,0.60)`, `blur: 24px`, `border: rgba(255,255,255,0.22)`
|
|
- **Accent**: `#fb923c` (Bitcoin orange), `#4ade80` (green), `#ef4444` (red)
|
|
- **Text**: `rgba(255,255,255,0.9)` primary, `rgba(255,255,255,0.6)` muted
|
|
|
|
### Rules
|
|
|
|
- Global CSS classes in `style.css` only — never inline Tailwind in components
|
|
- `.gradient-button` is **banned** — use `.glass-button`
|
|
- All components use `<script setup lang="ts">`
|
|
|
|
## API
|
|
|
|
```typescript
|
|
import { rpcClient } from '@/api/rpc-client'
|
|
|
|
await rpcClient.login('password')
|
|
await rpcClient.startPackage('bitcoin')
|
|
const metrics = await rpcClient.getMetrics()
|
|
```
|
|
|
|
State management via Pinia stores. WebSocket patches applied automatically.
|
|
|
|
## Build Output
|
|
|
|
- **Dev build**: `../web/dist/neode-ui/`
|
|
- **Docker build**: `dist/` (deployed to nginx)
|
|
- **Production deploy**: via `scripts/deploy-to-target.sh --live`
|
|
|
|
## License
|
|
|
|
MIT
|