From 4164a2216e26a9e4eb3296e804509d9290f41227 Mon Sep 17 00:00:00 2001 From: Anton Afanasyeu Date: Tue, 23 Jun 2026 17:07:30 +0200 Subject: [PATCH] docs: developer onboarding, fresh clone guide, secrets recovery Add DEVELOPER_SETUP, FRESH_ENV_CLONE, and SECRETS_AND_RECOVERY for the ac/* workspace; link from README for clean-laptop and lab credential procedures. Co-authored-by: Cursor --- DEVELOPER_SETUP.md | 68 ++++++++++++++++++++++ README.md | 8 +++ docs/FRESH_ENV_CLONE.md | 90 +++++++++++++++++++++++++++++ docs/SECRETS_AND_RECOVERY.md | 108 +++++++++++++++++++++++++++++++++++ 4 files changed, 274 insertions(+) create mode 100644 DEVELOPER_SETUP.md create mode 100644 docs/FRESH_ENV_CLONE.md create mode 100644 docs/SECRETS_AND_RECOVERY.md diff --git a/DEVELOPER_SETUP.md b/DEVELOPER_SETUP.md new file mode 100644 index 0000000..8c766a7 --- /dev/null +++ b/DEVELOPER_SETUP.md @@ -0,0 +1,68 @@ +# Developer setup — org `ac` + +**Clean machine?** Start with [docs/FRESH_ENV_CLONE.md](docs/FRESH_ENV_CLONE.md) and run `ac-scripts/fresh-clone-dev-env.sh`. + +Canonical entry point: **`ac-workspace`** (submodule manifest). + +```bash +git clone git://f0xx.org/ac/ac-workspace +cd ac-workspace +git checkout next +git submodule update --init --recursive +``` + +## Which repo for what + +| Area | Repo(s) | +|------|---------| +| Android app | `ac-mobile-android` | +| Issues / crash console PHP | `ac-ms-issues`, `ac-be-issues`, `ac-platform-php`, `ac-platform-web` | +| Auth / 2FA UI | `ac-be-auth`, `ac-ms-identity` | +| Graphs | `ac-ms-graphs`, `ac-be-graphs` | +| Tickets, RBAC, devices, remote access | `ac-ms-tickets`, `ac-ms-rbac`, `ac-ms-devices`, `ac-ms-remote-access`, matching `ac-be-*` | +| URL shortener | `ac-ms-url-shortener` (submodule in workspace) | +| Hub / builder | `ac-be-hub`, `ac-be-builder` | +| Nginx FE/BE snippets | `ac-platform-edge` (`fe/ac-fe.conf` for Gentoo FE) | +| DB schema / migrations | `ac-platform-db` | +| Lab deploy scripts | `ac-deploy` (`sim/cluster0/`) | +| Docs | `ac-docs` | + +Legacy monolith `git://f0xx.org/android_cast` is **frozen read-only** — do not commit there. + +## Local PHP (optional) + +1. Clone workspace as above. +2. Copy `ac-deploy/sim/cluster0/lab-seeds/backend/config/config.example.php` → `config/config.php` and set SQLite or local MariaDB. +3. Point a local vhost at `public/` with `base_path` `/app/androidcast_project/issues` (see `ac-platform-edge` fragments). + +## Lab cluster (cast01–03) + +Deployed tree on nodes: + +| Path | Content | +|------|---------| +| `/var/www/ac/workspace/` | `ac-workspace` + submodules | +| `/var/www/ac/composed/backend/` | overlay from `compose-lab-backend.sh` | +| `/var/www/ac/platform/` | shared session / footer helpers | +| cast01 `:3000` | Gitea browse UI (org **ac**, pull mirrors) | + +Scripts: `ac-deploy/sim/cluster0/scripts/` — run on cast01 as `ai` after NFS sync. + +**Secrets / recovery:** [docs/SECRETS_AND_RECOVERY.md](docs/SECRETS_AND_RECOVERY.md) — passwords, tokens, WireGuard, RSSH. +Lab shared files: `cluster/credentials.txt`, `cluster/secrets.lab.env` (from `secrets.lab.env.example`). + +**Public lab URL (after FE install):** `https://acl0.f0xx.org/app/androidcast_project/issues/` +**Gitea (lab):** `https://acl0.f0xx.org/app/androidcast_project/git/ac/` — `[gitea_admin]` in `credentials.txt` +FE config: `ac-platform-edge/fe/INSTALL.md` → `/etc/nginx/ac-fe.conf` on monstro (PO applies). + +## Mobile defaults + +Production REST base: `https://apps.f0xx.org/app/androidcast_project/issues/` +(`ac-mobile-android` → `BackendEndpoints.ISSUES_BASE`). For lab QA, override upload URL in app settings or build flavor. + +After migration, **minor app/BE version will bump**; unreleased older mobile builds may be rejected by lab/prod — always build from current `next`. + +## Tests + +- Android unit: `./gradlew :app:testDebugUnitTest` (from `ac-mobile-android` checkout). +- Cluster verify: `ac-deploy/sim/cluster0/scripts/verify_lab_setup.sh --local` / `--cluster`. diff --git a/README.md b/README.md index 111cb9c..3aa2ea1 100644 --- a/README.md +++ b/README.md @@ -5,3 +5,11 @@ AndroidCast documentation (extracted from monolith `docs/`). - **Remote:** `git://f0xx.org/ac/ac-docs` - **Build PDFs:** `./build-pdf.sh` (requires pandoc/xelatex per `_pdf_build/`) - **SPEC:** [specs/20260618_repos_reorganizing.md](specs/20260618_repos_reorganizing.md) Step 2 + +## Developer onboarding + +| Doc | Purpose | +|-----|---------| +| [DEVELOPER_SETUP.md](DEVELOPER_SETUP.md) | Repo map, lab paths | +| [docs/FRESH_ENV_CLONE.md](docs/FRESH_ENV_CLONE.md) | Clean laptop — clone all `ac/*` repos | +| [docs/SECRETS_AND_RECOVERY.md](docs/SECRETS_AND_RECOVERY.md) | Passwords, tokens, VPN/RSSH recovery | diff --git a/docs/FRESH_ENV_CLONE.md b/docs/FRESH_ENV_CLONE.md new file mode 100644 index 0000000..cf43aa4 --- /dev/null +++ b/docs/FRESH_ENV_CLONE.md @@ -0,0 +1,90 @@ +# Fresh developer machine — clone guide + +Use this on a **clean laptop** (no legacy `android_cast` monolith checkout). +Canonical layout: org **`ac`** on `git://f0xx.org/ac/*`, branch **`next`**. + +## One command (recommended) + +From any empty directory (requires `git` and reachability to `git://f0xx.org`): + +```bash +# Bootstrap: shallow clone ac-scripts only, then run the full workspace clone +git clone --branch next --single-branch --depth 1 \ + git://f0xx.org/ac/ac-scripts /tmp/ac-scripts-bootstrap +sh /tmp/ac-scripts-bootstrap/fresh-clone-dev-env.sh +``` + +Default target: `~/src/androidcast-ac/` (override with `-d /path`). + +The script: + +1. Clones **`ac-workspace`** (submodule manifest). +2. Runs `git submodule update --init --recursive` on **`next`**. +3. Verifies every submodule path exists and prints a SHA summary. +4. Exits non-zero if any submodule is missing or unreachable. + +## Manual steps (review / teach) + +```bash +export AC_GIT_BASE=git://f0xx.org/ac +export AC_BRANCH=next +export TARGET=~/src/androidcast-ac + +mkdir -p "$(dirname "$TARGET")" +git clone --branch "$AC_BRANCH" --single-branch \ + "${AC_GIT_BASE}/ac-workspace" "$TARGET" +cd "$TARGET" +git submodule sync --recursive +git submodule update --init --recursive + +# Sanity: expect 32 submodule directories + ac-workspace root +find . -maxdepth 1 -type d -name 'ac-*' | wc -l + +# Spot-check remotes (each submodule should be git://f0xx.org/ac/) +git submodule foreach --quiet 'echo $name $(git rev-parse --short HEAD) $(git remote get-url origin)' +``` + +## What you get + +| Path under workspace | Role | +|----------------------|------| +| `ac-mobile-android/` | Android app | +| `ac-deploy/` | Lab cluster (`sim/cluster0/`), compose scripts | +| `ac-docs/` | Documentation (this file) | +| `ac-scripts/` | `fresh-clone-dev-env.sh`, CI helpers | +| `ac-platform-*` | DB, PHP, web, edge nginx snippets | +| `ac-ms-*`, `ac-be-*` | Backend microservices and consoles | + +**Do not** clone legacy `git://f0xx.org/android_cast` for new work — it is frozen read-only. + +## After clone + +| Task | Where | +|------|--------| +| Repo map, lab URLs | [DEVELOPER_SETUP.md](../DEVELOPER_SETUP.md) | +| Passwords / tokens / VPN recovery | [SECRETS_AND_RECOVERY.md](SECRETS_AND_RECOVERY.md) | +| Android build | `cd ac-mobile-android && ./gradlew :app:assembleDebug` | +| Unit tests | `./gradlew :app:testDebugUnitTest` | +| Lab cluster (optional) | `ac-deploy/sim/cluster0/DEPLOY.md` | + +## Lab vs production URLs + +| Environment | Issues API | Gitea browse | +|-------------|------------|--------------| +| Production (current) | `https://apps.f0xx.org/app/androidcast_project/issues/` | prod BE Gitea | +| Lab cluster (cast01) | `https://acl0.f0xx.org/...` (after FE `ac-fe.conf`) | `.../git/ac/` | + +Mobile defaults target **production** until you point a debug build at lab (`BackendEndpoints` / settings). + +## Version note (post-migration) + +After migration completes, **app and backend minor versions will bump**. Older mobile builds were not publicly released; lab/prod may **reject** clients below the new minimum. Rebuild from `ac-mobile-android` on `next` after pulling. + +## Troubleshooting + +| Symptom | Fix | +|---------|-----| +| `git://f0xx.org` unreachable | VPN/LAN to git host; try from cluster or PO network | +| Submodule empty dir | `git submodule update --init --recursive` in workspace root | +| Wrong branch | `git checkout next && git submodule foreach git checkout next` | +| SSH instead of git | Not required for read-only clone; push uses `git://` on FE | diff --git a/docs/SECRETS_AND_RECOVERY.md b/docs/SECRETS_AND_RECOVERY.md new file mode 100644 index 0000000..5b0a886 --- /dev/null +++ b/docs/SECRETS_AND_RECOVERY.md @@ -0,0 +1,108 @@ +# Secrets, tokens, and recovery (lab cluster + dev) + +**Rule:** whenever you create a password, API token, or VPN key, **record it in the shared lab store** so the next deploy or developer can recover without guesswork. + +## Shared store (lab cluster) + +| File | Location | In git? | +|------|----------|---------| +| `credentials.txt` | `ac-deploy/sim/cluster0/` → NFS `/shared/cluster/` | **Yes** (lab-only values) | +| `secrets.lab.env` | same NFS tree | **No** — copy from `secrets.lab.env.example`, fill on cluster | +| Gitea install secrets | `/var/lib/gitea/.lab-secrets.env` on cast01 | **No** (generated by `deploy-gitea.sh`) | +| Gitea mirror API token | `/var/lib/gitea/.mirror-admin-token` on cast01 | **No** (regenerable — see below) | + +Production (`artc0` / `monstro`) keeps its own stores; lab cluster is **cast01–03**. + +## Recovery priority + +1. **Preferred:** user self-service via **email** (2FA, password reset) once cluster mail is configured and verified on `acl0`. +2. **Lab fallback:** admin CLI / config rewrite from values in `credentials.txt` + `secrets.lab.env`. +3. **VPN (WireGuard + RSSH):** re-provision from cluster scripts — never copy prod keys to lab. + +--- + +## Gitea (cast01) + +| Secret | Recover | +|--------|---------| +| Admin password `[gitea_admin]` | `credentials.txt` → or `gitea admin user change-password --username admin --password '…'` | +| Mirror API token | `sudo -u gitea gitea -c /etc/gitea/app.ini admin user generate-access-token --username admin --token-name mirror-ac --scopes all --raw` → save to `/var/lib/gitea/.mirror-admin-token` | +| `INTERNAL_TOKEN`, JWT | `/var/lib/gitea/.lab-secrets.env` — if lost: stop gitea, delete file, `FORCE_GITEA_CONFIG=1 deploy-gitea.sh` (rewrites `app.ini`; **DB preserved**) | + +Browse: `https://acl0.f0xx.org/app/androidcast_project/git/` (org **`ac`**). + +--- + +## MariaDB (cluster) + +| Item | Recover | +|------|---------| +| App user/password | `[mariadb_app]` in `credentials.txt` | +| Replication | `[mariadb_replication]` in `credentials.txt` | +| Root | Alpine socket auth as root on cast01 — no password by default | + +Re-apply schemas: `sudo sh /shared/cluster/scripts/load-schemas.sh` on cast01 (destructive to empty DB only — read script first). + +--- + +## PHP / issues backend (`config.php`) + +Lab composed tree: `/var/www/ac/composed/backend/config/config.php` (generated by `compose-lab-backend.sh`). + +| Key | Source | +|-----|--------| +| DB password | `credentials.txt` `[mariadb_app]` | +| `auth.encryption_key` | `secrets.lab.env` → `AUTH_ENCRYPTION_KEY` or regenerate (invalidates sessions) | + +Template: `ac-deploy/sim/cluster0/lab-seeds/backend/config/config.example.php`. + +**Email / 2FA:** when SMTP is live on lab, verify with `diag.php` and registration flow; then prefer **email recovery** over static passwords. + +--- + +## WireGuard (remote access) + +| Item | Store / recover | +|------|-----------------| +| Server keys | `secrets.lab.env` → `WG_SERVER_*` or BE `config.php` `remote_access` | +| Peer keys | DB `remote_access` tables + `WireGuardPeerProvisioner` | +| Re-provision | `ac-deploy/sim/cluster0/lab-seeds/backend/scripts/sync_wg_peers.php` (on cluster, from composed backend) | + +Do **not** reuse production WG keys on lab. Generate new lab keys and document in `secrets.lab.env`. + +--- + +## RSSH (bastion / reverse SSH) + +| Item | Store / recover | +|------|-----------------| +| Bastion host keys | server `sshd` host keys (standard OS path) | +| Ephemeral `ra-*` users | `scripts/rssh_bastion_user.sh` on composed backend | +| Client keys | issued per session in DB — no static shared password | + +Recovery: run bastion provisioner from lab backend; see `REMOTE_ACCESS_IMPL.md` and `REMOTE_ACCESS_VALIDATION.md`. + +--- + +## Git HTTPS read tokens (future) + +Per SPEC: tokens live under **`/etc/git-ro/`** on FE — **outside** app repos. +AndroidCast code does not read those paths; CI holds tokens in its own secret store. + +--- + +## Checklist after creating any secret + +- [ ] Added to `credentials.txt` (if safe for git — lab only) **or** `secrets.lab.env` on NFS (not committed). +- [ ] Noted in this doc if recovery command is non-obvious. +- [ ] If user-facing: email path tested on lab when mail is up. +- [ ] VPN: lab keys distinct from prod. + +--- + +## Related + +- [FRESH_ENV_CLONE.md](FRESH_ENV_CLONE.md) — clean laptop clone +- [DEVELOPER_SETUP.md](../DEVELOPER_SETUP.md) — repo map +- `ac-deploy/sim/cluster0/gitea/README.md` — Gitea deploy +- `20260607-2FA-email-mobile-auth-flow.md` — auth / email flows