dev_arc_aws/README.md

ArchNest

A self-hosted ops dashboard — infrastructure monitoring, a bookmark hub for your homelab/cloud links, an embedded terminal, and system settings, all in one place. Real backend, real integrations, no mock data.

Frontend: React 19 + TypeScript + Vite, styled with Tailwind CSS v4, charts via Recharts, icons via Lucide React. Backend: Fastify + TypeScript + SQLite (better-sqlite3), JWT auth, AES-256-GCM encrypted integration secrets.

For a full handoff/status writeup (what's done, what's not, how to resume), see HANDOFF.md.

Pages

Page	Route	Status
Glance	/	Done — real backend data (system status, resource overview, alerts, network traffic)
Infrastructure	/infrastructure	Done — resource distribution, node status grid, cost/trend breakdown, all from real integration data. "Network" sub-tab planned as a future addition.
BookNest	/booknest	Done — categorized bookmark hub wired to the real bookmarks API
Terminal	/terminal	Pending / on hold — will be based on a fork of the (archived) Termix project; user has the fork and intends to hand this off to another AI session to integrate. Do not start this without explicit instruction.
Settings	/settings	Done — Profile (real user identity + avatar, editable via API), Appearance, Integrations (8 real adapters), Notifications, Data & Backup, About

See archnest-blueprint.md for the original per-page design spec and design-decisions.md for the visual/UX conventions and lessons learned while building each page — read that file before making layout changes, it documents why things are built the way they are (hero banner layering, card blend techniques, icon library gotchas, etc.).

Development

Frontend:

npm install
npm run dev

Backend:

cd backend
npm install
ARCHNEST_SECRET_KEY=$(openssl rand -hex 32) ARCHNEST_JWT_SECRET=$(openssl rand -hex 32) npm run dev

Both ARCHNEST_SECRET_KEY (encrypts integration secrets at rest) and ARCHNEST_JWT_SECRET (signs auth tokens) are required env vars with no defaults — the server will refuse to start without them. ARCHNEST_DB_PATH optionally overrides the SQLite file location (defaults to a local path under backend/). PORT overrides the listen port (default 4000-range, check server.ts).

Type-check both before committing:

npx tsc --noEmit          # from repo root, frontend
cd backend && npx tsc --noEmit   # backend

Vite/the browser surface some runtime errors (e.g. missing icon exports) that the type-checker won't catch, so also smoke-test pages in a browser.

Tech Stack

Frontend

• React 19 + Vite + TypeScript
• React Router for routing
• Tailwind CSS v4
• Recharts (donuts, line/area charts)
• Lucide React (icons)

Backend

• Fastify 5 + TypeScript, tsx for dev, tsc -b for build
• better-sqlite3 for storage
• @fastify/jwt for auth tokens, bcryptjs for password hashing
• zod for request validation
• AES-256-GCM (Node crypto) for encrypting integration secrets at rest
• Integration adapters: Proxmox, Docker, NetBird, Cloudflare, AWS, Uptime Kuma, Weather, SSH (see backend/src/integrations/)

Deploy target: Docker on racknerd1 → NPM (Nginx Proxy Manager) proxy at archnest.snsnetlabs.com.

Deployment

Live and deployed at archnest.snsnetlabs.com. The pipeline at .github/workflows/deploy.yml triggers on every push to main: it copies the repo to racknerd1 over SCP and runs docker compose up -d --build there, gated on an /api/health check. No further setup is needed — merging a PR to main redeploys automatically.

If a deploy fails, check the workflow run's deploy job steps in order: Pre-flight (confirms host .env exists), Copy repo to racknerd1, Build, restart, and clean up, Health check (backend /api/health).

For reference, the one-time setup that was done to stand this up: host provisioning (Docker/Compose on racknerd1, deploy SSH user, /opt/archnest directory), /opt/archnest/.env populated from .env.example with real secrets, RACKNERD_HOST/RACKNERD_USER/RACKNERD_SSH_KEY added as GitHub Actions secrets, and DNS/Nginx Proxy Manager pointed at the host.

See HANDOFF.md for current feature work in progress (multi-user accounts, SSO, security settings).