sunfish-admin
12d2179c20
Ship Magisk like GOLDEN; KernelSU optional recycle only; parallel to sunfish-a16-rom standby.
209 lines
13 KiB
Markdown
209 lines
13 KiB
Markdown
# Tasks: Development environment on rom-dev01
|
||
|
||
**Input**: Design documents from `/specs/001-development-environment/`
|
||
|
||
**Prerequisites**: plan.md (required), spec.md, research.md, data-model.md,
|
||
quickstart.md, contracts/ (N/A)
|
||
|
||
**Tests**: Observational verify steps embedded in tasks (no separate TDD suite).
|
||
|
||
**Organization**: Setup → Foundational (preflight) → User stories by priority →
|
||
Polish. **Do not run these tasks until `rom-dev01` SSH works.** Generating this
|
||
file is documentation-only.
|
||
|
||
**Canonical paths**:
|
||
- Meta Spec Kit tree: `/home/android-build/sunfish-a16-rom`
|
||
- Data root: `/srv/rom/`
|
||
- Automation repo (after Gitea): `sunfish-rom-build` (not the meta repo)
|
||
|
||
## Format: `[ID] [P?] [Story] Description`
|
||
|
||
- **[P]**: Can run in parallel (different files, no incomplete dependencies)
|
||
- **[Story]**: US1…US5 from spec.md
|
||
- Every task includes a path and an observable verify hint
|
||
|
||
## Path Conventions
|
||
|
||
Host paths are absolute on `rom-dev01`. Docs/logs also land under
|
||
`/home/android-build/sunfish-a16-rom/docs/` or `/srv/rom/logs/` as noted.
|
||
|
||
---
|
||
|
||
## Phase 1: Setup (docs readiness — can be done on laptop before VM)
|
||
|
||
- [x] T001 Confirm active feature is `specs/001-development-environment` via `.specify/feature.json` and that constitution is `0.1.7` in `.specify/memory/constitution.md`
|
||
- [x] T002 [P] Create host-facing doc stub `docs/001-host-runbook.md` in meta repo (preflight results, paths, Gitea tunnel notes — fill during implement)
|
||
- [x] T003 [P] Create FR/SC evidence checklist stub `docs/001-verification-matrix.md` mapping each FR-*/SC-* from `specs/001-development-environment/spec.md` to blank evidence fields
|
||
|
||
---
|
||
|
||
## Phase 2: Foundational (blocking — host preflight before stories)
|
||
|
||
**Goal**: Observe `rom-dev01` without fighting `saltenv=base`; abort on conflict.
|
||
|
||
- [x] T004 On `rom-dev01` as admin, capture preflight baseline into `/srv/rom/logs/preflight/` (create `/srv/rom/logs` with safe perms if needed): Ubuntu/kernel, CPU/RAM/swap, disk free, interfaces/routes, users, firewall summary (**do not flush**), listening ports, apt sources → also summarize in `docs/001-host-runbook.md`
|
||
- [x] T005 Record coexistence rule in `docs/001-host-runbook.md`: if base-managed config conflicts with project needs, **stop and report**; do not silently replace Salt-managed settings
|
||
- [x] T006 Verify SSH admin path still works after any read-only inspection; note rollback contacts/commands in `docs/001-host-runbook.md`
|
||
|
||
---
|
||
|
||
## Phase 3: User Story 1 — Reachable build workspace (P1)
|
||
|
||
**Story goal**: `android-build` exists with SSH key login from laptop; `/srv/rom` owned correctly; meta tree at fixed path.
|
||
|
||
**Independent test**: `ssh android-build@rom-dev01` from laptop; `/srv/rom/artifacts` writable; `/home/android-build/sunfish-a16-rom` contains Spec Kit tree (after T013).
|
||
|
||
### Implementation
|
||
|
||
- [x] T007 [US1] Create unprivileged user `android-build` with home `/home/android-build` (admin); document uid/gid in `docs/001-host-runbook.md`
|
||
- [x] T008 [US1] Configure SSH public-key access for `android-build` using the developer's existing public key only (do not copy private keys; do not modify global sshd/`saltenv=base` policy unless required). Verify from the laptop that `ssh android-build@rom-dev01` succeeds. Document Cursor `Host` entry (`User android-build`) in `docs/001-host-runbook.md`
|
||
- [x] T009 [US1] Create `/srv/rom/{src,references,tooling,ccache,artifacts,logs,secrets}` with ownership for `android-build` on writable trees; `secrets/` restricted/empty — document modes in `docs/001-host-runbook.md`
|
||
- [x] T010 [US1] Verify: `namei -l /srv/rom /srv/rom/artifacts` and `sudo -iu android-build touch /srv/rom/artifacts/.write_test` succeeds; no `chmod 777`
|
||
- [x] T011 [US1] Document account model (admin vs `android-build` vs service users) in `docs/001-host-runbook.md` — never build Android as root
|
||
- [x] T012 [US1] Copy laptop staging Git tree to `/home/android-build/sunfish-a16-rom` preserving `.git` (rsync/scp/bundle); verify `test -f /home/android-build/sunfish-a16-rom/specs/001-development-environment/spec.md`
|
||
- [x] T013 [US1] Ensure `/srv/rom/tooling` is **not** used as Spec Kit checkout; note distinction in `docs/001-host-runbook.md`
|
||
|
||
---
|
||
|
||
## Phase 4: User Story 2 — Android host toolchain (P1)
|
||
|
||
**Story goal**: Clean-login toolchain ready for later `003` (no `repo sync` / build).
|
||
|
||
**Independent test**: `ssh android-build@rom-dev01` → `git`, `git lfs`, `repo`, `python3`, `ccache -s`, and LOS-doc Java/prereqs succeed.
|
||
|
||
### Implementation
|
||
|
||
- [x] T014 [US2] As admin, install host packages per **current** primary LineageOS/AOSP Ubuntu build documentation; record exact package list in `/srv/rom/logs/toolchain-packages.txt`
|
||
- [x] T015 [US2] Install/configure `repo` for `android-build` per current docs; verify `ssh android-build@rom-dev01 'repo --version'`
|
||
- [x] T016 [US2] Ensure `git` + `git-lfs` for `android-build`; verify `ssh android-build@rom-dev01 'git lfs version'`
|
||
- [x] T017 [US2] Configure ccache: `CCACHE_DIR=/srv/rom/ccache`, ownership `android-build`, size cap; document env in `/home/android-build/.bashrc` or `/home/android-build/.profile` and `docs/001-host-runbook.md`
|
||
- [x] T018 [US2] Verify: `ssh android-build@rom-dev01 'ccache -s'` shows configured cache dir
|
||
- [x] T019 [US2] Document FR-007 capacity (6 vCPU / 52 GB / 32 GB swap) and **defer `-j`/OOM tuning to `003`** in `docs/001-host-runbook.md` — do not run a Lineage build
|
||
- [x] T020 [US2] Clean-shell toolchain smoke checklist executed; paste command outputs into `/srv/rom/logs/toolchain-smoke.txt` and tick FR-002/SC-001 in `docs/001-verification-matrix.md`
|
||
|
||
---
|
||
|
||
## Phase 5: User Story 5 — Laptop thin client (P1/P2 overlap — do after US1–US2)
|
||
|
||
**Story goal**: Cursor Remote SSH as `android-build` + artifact rsync proven; Pixel stays on laptop USB.
|
||
|
||
**Independent test**: Remote SSH edit on host as `android-build`; dummy artifact SHA256 matches after rsync; laptop has `adb`/`fastboot` binaries.
|
||
|
||
### Implementation
|
||
|
||
- [x] T021 [US5] Document Cursor Remote SSH → `/home/android-build/sunfish-a16-rom` with `User android-build` in `docs/001-host-runbook.md` and update `specs/001-development-environment/quickstart.md` if needed
|
||
- [x] T022 [US5] Create `/srv/rom/artifacts/dummy-001.txt` as `android-build`; record `sha256sum` in `/srv/rom/logs/rsync-smoke.txt`
|
||
- [x] T023 [US5] From laptop, `rsync` dummy artifact; verify SHA256 match; record laptop path in `/srv/rom/logs/rsync-smoke.txt` and `docs/001-verification-matrix.md` (SC-002)
|
||
- [x] T024 [US5] On laptop only: run `adb --version` and `fastboot --version` (do **not** connect or flash the Pixel); record versions in `docs/001-host-runbook.md`. Document adb/fastboot-on-laptop / no USB passthrough rule (SC-004 partial)
|
||
|
||
---
|
||
|
||
## Phase 6: User Story 3 — Gitea, Ansible, Semaphore, off-VM mirror (P2)
|
||
|
||
**Story goal**: Private Gitea with four repos; canonical meta remote; `sunfish-rom-build` committed+pushed; laptop pull mirrors; unprivileged Semaphore smoke from canonical repo.
|
||
|
||
**Independent test**: Four repos on Gitea; meta history pushed; `sunfish-rom-build` fetch shows smoke playbook commit; laptop `git clone --mirror` works; Semaphore runs unprivileged smoke.
|
||
|
||
### Implementation
|
||
|
||
- [x] T025 [US3] Install Gitea on `rom-dev01` with systemd + persistent data; bind UI to loopback/non-public; document unit/paths in `docs/001-host-runbook.md`
|
||
- [x] T026 [US3] Store Gitea admin credentials only in restricted host location under `/srv/rom/secrets/` or service-native secret path — **never** commit to Git; document location (not secrets) in `docs/001-host-runbook.md`
|
||
- [x] T027 [US3] Verify: local `curl` to Gitea UI succeeds; confirm not relying on public Internet exposure; record bind address in `docs/001-host-runbook.md`
|
||
- [x] T028 [US3] Document Git transport chosen after host inspection (HTTP via SSH tunnel and/or tunneled Git SSH); **do not** open public `:2222` or blindly edit `saltenv=base` sshd — write choice in `docs/001-host-runbook.md`
|
||
- [x] T029 [US3] Create Gitea repos: `sunfish-a16-rom`, `sunfish-rom-manifest`, `sunfish-rom-build`, `sunfish-rom-patches`
|
||
- [x] T030 [US3] Push `/home/android-build/sunfish-a16-rom` history to Gitea `sunfish-a16-rom`; set `origin` to Gitea; verify remote in that directory
|
||
- [x] T031 [US3] Seed minimal structure in a working tree of `sunfish-rom-build` for Ansible (e.g. `ansible/` playbooks path) — **not** inside Spec Kit meta repo
|
||
- [x] T032 [US3] Install Ansible on `rom-dev01`; document version in `docs/001-host-runbook.md`
|
||
- [x] T033 [US3] Add unprivileged smoke playbook under `sunfish-rom-build` (gather_facts + asserts for `/srv/rom`, `android-build`, toolchain); **no become/sudo secrets**
|
||
- [x] T034 [US3] Run smoke playbook successfully via `ansible-playbook` CLI; log output to `/srv/rom/logs/ansible-smoke.txt`
|
||
- [x] T035 [US3] Commit and push the initial `sunfish-rom-build` structure and smoke playbook to its canonical Gitea repository; verify the pushed commit is visible from a fresh fetch/clone (document clone URL/path in `docs/001-host-runbook.md`)
|
||
- [x] T036 [US3] Install Semaphore; bind like Gitea (loopback/tunnel); no public exposure; document in `docs/001-host-runbook.md`
|
||
- [x] T037 [US3] Wire Semaphore so it executes the smoke playbook **originating from the canonical `sunfish-rom-build` repository**, using the simplest private mechanism supported by the actual installation (token/HTTP/SSH — decide at implement). Run once successfully; evidence in `/srv/rom/logs/semaphore-smoke.txt` (FR-005). Still unprivileged / no sudo password in Semaphore
|
||
- [x] T038 [US3] From **laptop**, create bare mirrors with `git clone --mirror` for all four repos (laptop initiates connection); run `git remote update` + `git fsck`; document mirror paths in `docs/001-host-runbook.md` (FR-010/SC-007)
|
||
- [x] T039 [US3] Confirm laptop staging `/home/aventura/Workspaces/sunfish-a16-rom` is **retained** until T030+T035+T038 verified; only then optionally mark staging as non-canonical in `docs/001-host-runbook.md`
|
||
|
||
---
|
||
|
||
## Phase 7: User Story 4 — Guest isolation (P2)
|
||
|
||
**Story goal**: Isolation checklist passes without breaking SSH.
|
||
|
||
**Independent test**: Public-NIC-only workflow; UIs non-public; SSH still works; no VPN/internal DNS required in docs.
|
||
|
||
### Implementation
|
||
|
||
- [x] T040 [US4] Document interfaces/routes: project workflow requires only public NIC — `docs/001-host-runbook.md` + evidence in `docs/001-verification-matrix.md` (SC-006)
|
||
- [x] T041 [US4] Apply isolation/firewall guidance **additively** if needed: never flush nftables/iptables; never close active SSH before tested alternative; record before/after in `/srv/rom/logs/firewall-notes.txt`
|
||
- [x] T042 [US4] Re-verify Gitea/Semaphore binds remain non-public; SSH admin + `android-build` + tunnel still work — update `docs/001-verification-matrix.md` FR-009/SC-006
|
||
- [x] T043 [US4] Confirm day-to-day runbook does not require SSYSTEMS VPN/internal DNS/LDAP/GitLab/NFS/Zabbix — `docs/001-host-runbook.md`
|
||
|
||
---
|
||
|
||
## Phase 8: Polish & cross-cutting
|
||
|
||
- [x] T044 [P] Fill all FR-*/SC-* evidence rows in `docs/001-verification-matrix.md` (including SC-005: no PVE/qm/Salt VM tasks were performed)
|
||
- [x] T045 [P] Align `specs/001-development-environment/quickstart.md` with final ports/paths/tunnel commands actually used
|
||
- [x] T046 Restart Gitea (+ Semaphore) via systemd; confirm recovery; optional reboot when safe; note results in `/srv/rom/logs/restart-smoke.txt`
|
||
- [x] T047 Declare handoff in `docs/001-host-runbook.md`: **`001` complete → proceed to `002`**, do not start Lineage sync/build
|
||
- [x] T048 Verify that no credentials/tokens/private keys are present in the **current trees OR committed history** of `sunfish-a16-rom` and `sunfish-rom-build`. Review current files plus reachable Git history; if a secret was ever committed, remove it from history and rotate/revoke it before closing `001`. Method may be manual/`git log -p`/`git rev-list` review (no mandatory Gitleaks/TruffleHog)
|
||
|
||
---
|
||
|
||
## Dependencies & story order
|
||
|
||
```text
|
||
Phase 1 (laptop docs)
|
||
↓
|
||
Phase 2 preflight (host)
|
||
↓
|
||
US1 user + SSH key + /srv/rom + meta copy
|
||
↓
|
||
US2 toolchain ──────────────┐
|
||
↓ │
|
||
US5 thin-client smokes ←───┘ (needs artifacts + meta path + android-build SSH)
|
||
↓
|
||
US3 Gitea → repos → Ansible in sunfish-rom-build → commit/push → Semaphore → laptop mirrors
|
||
↓
|
||
US4 isolation hardening/validation
|
||
↓
|
||
Polish / handoff → STOP until implement; next feature 002 after 001 done
|
||
```
|
||
|
||
**MVP (minimum useful host)**: complete through US2 + US5 (T007–T024) even if Gitea delayed — but **formal `001` done** requires P2 (US3+US4+polish) per plan.
|
||
|
||
## Parallel opportunities
|
||
|
||
- T002/T003 on laptop before VM
|
||
- After T009: T011 docs can parallel T012 copy if disk ready
|
||
- T014–T016 package/`repo`/`git-lfs` partly serial (apt) then T017 ccache
|
||
- T044/T045 polish docs in parallel after evidence exists
|
||
|
||
## FR/SC coverage map
|
||
|
||
| ID | Tasks |
|
||
|----|-------|
|
||
| FR-001 | T007–T011, T008 |
|
||
| FR-002 | T014–T018, T020 |
|
||
| FR-003 | T009–T010, T013 |
|
||
| FR-004 | T025–T030 |
|
||
| FR-005 | T031–T037 |
|
||
| FR-006 | T021–T024 |
|
||
| FR-007 | T019 |
|
||
| FR-008 | T012, T030 |
|
||
| FR-009 | T040–T043 |
|
||
| FR-010 | T038–T039 |
|
||
| SC-001 | T020 |
|
||
| SC-002 | T022–T023 |
|
||
| SC-003 | T029–T030 |
|
||
| SC-004 | T021, T024, T047 |
|
||
| SC-005 | T005, T044 |
|
||
| SC-006 | T040–T043 |
|
||
| SC-007 | T038 |
|
||
|
||
## Implementation strategy
|
||
|
||
1. Do **not** execute host tasks until SSH to `rom-dev01` works.
|
||
2. After analyze approval: STOP until VM exists, then `/speckit-implement`.
|
||
3. Follow P1 then P2; stop/report on Salt conflicts.
|
||
4. Do not plan `002` until `001` implement + verification complete.
|