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 <cursoragent@cursor.com>
2026-07-29 04:39:12 +03:00 · 2026-06-23 17:07:30 +02:00
parent d958b9413c
commit 4164a2216e
4 changed files with 274 additions and 0 deletions
--- a/docs/FRESH_ENV_CLONE.md
+++ 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/<name>)
+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 |
--- a/docs/SECRETS_AND_RECOVERY.md
+++ 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