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

All features are built and verified. The only remaining work to go live is wiring up the GitHub Actions deploy pipeline — the app itself does not need further development before deployment.

The workflow already exists at .github/workflows/deploy.yml and triggers on every push to main: it copies the repo to racknerd1 over SCP and runs docker compose up -d --build there. Nothing in that file needs to change. To activate it:

1. Provision the host (racknerd1): Docker + Docker Compose installed, an SSH user the Action can authenticate as, and /opt/archnest created and owned by that user (matches DEPLOY_PATH in the workflow — change both together if a different path is wanted).
2. Create /opt/archnest/.env on the host (Compose reads it automatically) using the repo's top-level .env.example as the template — generate real values for ARCHNEST_JWT_SECRET, ARCHNEST_SECRET_KEY, and ARCHNEST_GUAC_CRYPT_KEY (commands included inline in the example file), and set ARCHNEST_CORS_ORIGIN to the real public origin if different from the default. This file is server-side only and must never be committed.
3. Add the deploy secrets in the GitHub repo settings (Settings → Secrets and variables → Actions): RACKNERD_HOST, RACKNERD_USER, RACKNERD_SSH_KEY (private key for that user, PEM format), and optionally RACKNERD_PORT if SSH isn't on port 22.
4. Point DNS / Nginx Proxy Manager at the host: a proxy host for archnest.snsnetlabs.com forwarding to the container's published port (8080 for the frontend, see docker-compose.yml), with SSL handled by NPM as usual.
5. Trigger the first deploy — either push to main, or run the workflow manually via the Actions tab (workflow_dispatch is enabled).

After that, every push to main redeploys automatically. No code changes are expected to be part of standing up this pipeline — it's configuration only (host setup, secrets, DNS/proxy).