dev_arc_aws/docs/OPEN-SOURCE-RELEASE.md

# ArchNest — Open-Source Release Readiness (v1)

This document is the checklist + plan for publishing ArchNest as an open-source
project. It is an internal planning doc — **do not copy this file into the public
repo.** It covers what to copy, what to scrub, licensing, repo structure,
README/screenshots, the release cadence, and resume/LinkedIn framing.

The public OSS repo should be a **fresh repository with a clean history** (see
"Why a fresh repo" below), not a fork of the working repo.

---

## 1. Security sweep result (done 2026-06-22)

A full secret/credential sweep of tracked files **and entire git history**
(`git log --all -p`) was run. Result: **clean — no real secrets are committed.**

- No private keys, no hardcoded secret assignments in tracked source.
- No real `.env`, `.pem`, `.key`, or `.db` was ever committed at any point in
  history. The only `BEGIN RSA PRIVATE KEY` / `AKIA…` matches are documentation
  prose and AWS's official `AKIAIOSFODNN7EXAMPLE` placeholder.
- `.gitignore` correctly excludes `backend/.env`, `backend/data`, `*.db`.
- Both `.env.example` files contain only placeholders (empty / `change-me-…`).

### Code-level security review (solid)
- JWT auth (Fastify `@fastify/jwt`). Every route group registers a blanket
  `addHook('onRequest', app.authenticate)` before its routes; the three
  WebSocket routes (`terminal`, `docker`, `guacamole`) verify
  `app.jwt.verify(query.token)` explicitly (WS can't use header hooks).
- Mutating shared-config endpoints (integrations, tunnels, data export/import,
  user management) are gated by `adminOnly` / `requireAdmin`. `authenticate`
  re-reads `role`/`active` from the DB each request, so demote/deactivate takes
  effect immediately even with an older token.
- Integration secrets: `serialize()` returns only secret **key names**
  (`secretKeys`), never values. Secrets are encrypted at rest (AES-256-GCM,
  `backend/src/db/crypto.ts`).
- Docker agent ingest is a **separately registered** route with a constant-time
  bearer-token check; returns 503 when `ARCHNEST_AGENT_TOKEN` is unset (disabled
  by default), and is NOT behind the user-auth hook (by design).
- Command-injection surfaces are guarded: tmux session names validated against
  `^[A-Za-z0-9_-]{1,64}$` before interpolation; `system.ts` uses `execFile` (no
  shell); Docker-over-SSH single-quotes container refs.

### Things to improve / note for OSS (not leaks)
- **CORS default**: `server.ts` does `origin: process.env.ARCHNEST_CORS_ORIGIN ?? true`.
  `true` reflects any origin. Fine for a self-hosted single-origin deploy, but the
  OSS README should tell users to set `ARCHNEST_CORS_ORIGIN` in production, and the
  default `.env.example` should point at `http://localhost:5173` (it already does
  for the backend example).
- Default JWT/secret env values in `backend/.env.example` are `change-me-…` — the
  README must stress generating real ones (`openssl rand -hex 32`). The server
  already refuses to boot without `ARCHNEST_SECRET_KEY` + `ARCHNEST_JWT_SECRET`.

---

## 2. What to SCRUB / NOT copy to the public repo

None of these are security leaks, but they are personal/infra-specific or
internal working notes that don't belong in a public project:

| Item | Why | Action |
|---|---|---|
| `docs/rdp-debug-handoff.md` | Contains lab creds (`sam` / `happy2026`) + private VM IP `192.168.122.55` + personal host names | **Exclude** (or heavily genericize into a "Remote Desktop setup" guide with no creds/IPs) |
| `HANDOFF.md` | Internal session-to-session working notes | **Exclude** |
| `docs/OPEN-SOURCE-RELEASE.md` (this file) | Internal release plan | **Exclude** |
| `archnest.snsnetlabs.com` references in `.env.example`, `docker-compose.yml` | Personal domain/deploy target | **Genericize** to `example.com` / `localhost` |
| Forgejo CI (`.forgejo/workflows/`) | Already build/validate only (no SCP/personal server). The build workflow pushes to a private registry + deploys to a private host | **Keep but genericize** the registry host + deploy job, or strip the deploy job for a public build-only CI |
| `agent/` deploy specifics | Fine to include the agent script, but scrub any host-specific URLs/tokens in its README | **Review + genericize** |
| `assets/` personal background images | Large PNGs; keep the ones the UI needs (hero banner, logo, KPI backgrounds), drop unused experiments (`opt1.bg`, `settings-custom-bg`, `pics/`) | **Trim to what's referenced** |
| Test/scratch files | `backend/data/`, any `*.db`, session logs | Already gitignored — confirm none are force-added |

Keep `ROADMAP.md` and `TERMIX_MIGRATION.md`? — `ROADMAP.md` yes (genericize:
it's a fine public roadmap once paid-tier framing is softened). `TERMIX_MIGRATION.md`
is build history; optional — can keep as `docs/HISTORY.md` or drop.

---

## 3. Why a fresh repo (recommended)

The working repo's history contains personal commit author emails, the personal
deploy workflow, the lab-cred debug doc, and the personal domain. The simplest
clean cut for a public project:

1. Create a new empty public repo (e.g. `archnest` under the personal GitHub).
2. Copy the **working tree** (not `.git`) of the files in the "INCLUDE" list below.
3. Genericize the scrubbed items.
4. `git init`, single initial commit ("Initial public release — ArchNest v1"),
   author set to the public identity.
5. Add `LICENSE`, public `README.md`, `CONTRIBUTING.md`, screenshots.

This avoids dragging history-scrubbing tooling (BFG/`git filter-repo`) and
guarantees nothing personal leaks via an old commit.

### INCLUDE (the actual app)
```
src/                      # React frontend
backend/src/              # Fastify backend
backend/package.json, backend/tsconfig*.json, backend/Dockerfile
backend/.env.example      # (placeholders only — already clean)
package.json, package-lock.json, tsconfig*.json, vite.config.*, index.html
Dockerfile, docker-compose.yml   # genericized (no personal domain)
.env.example              # genericized
.gitignore, .dockerignore
public/                   # fonts + static assets actually referenced
assets/                   # ONLY images the UI imports
agent/archnest-docker-agent.sh + a genericized agent/README.md
design-decisions.md, ROADMAP.md   # genericized
.kiro/steering/design-rules.md    # optional — useful for contributors
LICENSE, README.md, CONTRIBUTING.md, screenshots/   # new, written for OSS
```

### EXCLUDE
```
.git/                     # fresh history instead
HANDOFF.md
docs/rdp-debug-handoff.md
docs/OPEN-SOURCE-RELEASE.md   (this file)
.forgejo/workflows/   (genericize: strip registry host + deploy job, or build-only CI)
backend/data/, *.db, session logs, *.tsbuildinfo
unused assets/ experiments + pics/
```

---

## 4. License

Recommended: **MIT** or **Apache-2.0**.
- **MIT** — shortest, most permissive, maximum adoption, easiest "I built this"
  story. Good default for a portfolio/resume project.
- **Apache-2.0** — same permissiveness plus an explicit patent grant and a
  NOTICE mechanism; slightly more "enterprise-friendly."

Given the goal (resume/LinkedIn showcase, broad adoption, simple), **MIT** is the
recommendation. Add a `LICENSE` file with the chosen license and the author's name
+ year. Note third-party components keep their own licenses (Guacamole = Apache-2.0,
the bundled Nerd Font has its own license already in `public/fonts/NERD-FONTS-LICENSE.txt`).

---

## 5. README.md (public) — outline

1. **Hero**: one-line pitch + a screenshot/GIF of the Glance dashboard.
   > "A self-hosted, web-based control panel for your homelab and cloud — SSH
   > terminal, file manager, Docker, tunnels, RDP/VNC, host metrics, and
   > integration dashboards, all in one browser tab."
2. **Screenshots** (see §6).
3. **Features** — bullet list grouped by page; mark paid add-ons / not-yet-done
   honestly (mirror the in-app Help "Not in the open-source version" notes).
4. **Architecture** — short: React + Vite + TS frontend, Fastify + SQLite backend,
   guacd sidecar for RDP/VNC. One diagram is plenty.
5. **Quick start** — `docker compose up` path + the required env vars (with
   `openssl rand -hex 32` generation), and the local-dev path (`npm install` /
   `npm run dev` in root and `backend/`).
6. **Configuration** — env var table (from `.env.example`), CORS note, first-run
   `/api/setup` admin creation, the 10-user cap.
7. **Security notes** — secrets encrypted at rest; set a real CORS origin in prod;
   it's designed to sit behind your own mesh/VPN, not be exposed raw to the
   internet (mesh prerequisite gate exists, defaults off).
8. **Roadmap** — link `ROADMAP.md` + the "updates ~every 3 months" promise.
9. **Contributing** — link `CONTRIBUTING.md`.
10. **License** — MIT.
11. **Credits / "Built with AI"** — see §7.

---

## 6. Screenshots to capture (for README + LinkedIn)

Capture in the **default dark theme**, with demo/sanitized data (no real
hostnames, IPs, or tokens — use the placeholder-y names):
- Glance dashboard (hero shot)
- Infrastructure → Node Status with a couple of integrations
- Terminal with a split-pane / multiple tabs
- Files (SFTP browser) + a host-to-host transfer in progress
- Containers list + a container detail tab
- Remote Desktop showing a live XFCE session
- Host Metrics widgets
- Settings → Integrations (shows the breadth) and the locked Appearance "Paid
  add-on" card (shows the free/paid split honestly)
- Help page (shows the per-page docs + OSS-edition note)

A short screen-recording GIF of opening a terminal or RDP session makes the
strongest LinkedIn post.

---

## 7. Resume / LinkedIn framing

Honest, specific, and ownership-forward. Suggested phrasing:

> **ArchNest** — a self-hosted, web-based homelab/cloud control panel
> (React + TypeScript + Fastify + SQLite, Dockerized). Single-pane access to SSH
> terminals, SFTP, Docker, SSH tunnels, browser-based RDP/VNC (Apache Guacamole),
> live host metrics, and pluggable infrastructure integrations (Proxmox, AWS,
> Cloudflare, NetBird, Uptime Kuma). Built with AI-assisted development; I owned
> the architecture, product decisions, security review, and integration/debugging
> (e.g. root-caused and fixed a FreeRDP/NLA + Guacamole tunnel-keepalive issue
> end-to-end across browser, proxy, and target VM). Open source under MIT, shipped
> v1, ongoing ~quarterly releases.

Notes for credibility:
- It's fine and increasingly normal to say "AI-assisted." Pair it with the
  *engineering judgment* you provided (architecture, security, debugging) so it
  reads as "I directed and verified," not "I prompted and pasted."
- The RDP debugging saga is a genuinely strong, concrete story — it shows
  multi-layer debugging (browser ↔ guacd/FreeRDP ↔ xrdp/desktop) and root-cause
  rigor. Worth a short LinkedIn write-up on its own.

---

## 8. Pre-publish checklist

- [ ] Create fresh public repo, copy INCLUDE list, exclude EXCLUDE list.
- [ ] Genericize personal domain → `example.com`/`localhost` in
      `.env.example`, `docker-compose.yml`.
- [ ] Genericize `.forgejo/workflows/` for public use (strip the private registry host + the racknerd2 deploy job, or ship build-only CI).
- [ ] Add `LICENSE` (MIT), public `README.md`, `CONTRIBUTING.md`.
- [ ] Capture + add screenshots (sanitized data, dark theme).
- [ ] Re-run a secret scan on the NEW repo before first push
      (`git log -p | grep -iE 'AKIA|BEGIN .*PRIVATE KEY|password|secret'` plus a
      tool like `gitleaks detect` for good measure).
- [ ] Confirm `npm run build` (root) and `npx tsc --noEmit` (backend) pass on the
      copied tree.
- [ ] Confirm first-run works from a clean `docker compose up` with freshly
      generated secrets and no prior DB.
- [ ] Tag `v1.0.0`.

---

## 9. Release cadence (commitment)

Public promise: **updates approximately every 3 months.** Keep a short
`CHANGELOG.md` in the public repo and cut a tagged release each cycle. The Help
page's "Open-source edition" note and the README both reference this cadence —
keep them in sync.