From 28523375b90102980e27290797d7333379152840 Mon Sep 17 00:00:00 2001 From: Simone Date: Thu, 14 May 2026 18:27:57 +0200 Subject: [PATCH] docs(plans): add A->B bridge checklist (windows prereqs + baseline + logistics) Bridges the gap between PhaseA-user-checklist.md (Windows validation) and PhaseB-user-checklist.md (Linux setup): Section 1: capture pre-migration benchmark to docs/RUNBOOK.md (referenced by B7) Section 2: 7 Windows prerequisites (SSH keys, BuildVMGuest password, Gitea PAT, OpenSSH server, template power-off check per AGENTS.md #9, F:\CI\ backup, scheduled task cadence audit) Section 3: logistics (hardware, DNS, maintenance window, user comms) --- plans/PhaseAB-bridge-user-checklist.md | 211 +++++++++++++++++++++++++ 1 file changed, 211 insertions(+) create mode 100644 plans/PhaseAB-bridge-user-checklist.md diff --git a/plans/PhaseAB-bridge-user-checklist.md b/plans/PhaseAB-bridge-user-checklist.md new file mode 100644 index 0000000..ffa8874 --- /dev/null +++ b/plans/PhaseAB-bridge-user-checklist.md @@ -0,0 +1,211 @@ +# Fase A → Fase B — Bridge checklist per l'utente + +Questa checklist copre i passi **intermedi** tra "Fase A done" e "B1 +inizia". Sono attività che girano sull'host **Windows attuale** (o sono +logistiche fuori dal repo) e non rientrano né in +[PhaseA-user-checklist.md](PhaseA-user-checklist.md) (validazione del +codice Python) né in [PhaseB-user-checklist.md](PhaseB-user-checklist.md) +(setup del nuovo host Linux). + +> **Quando eseguirla**: dopo Passo 9 di Fase A (merge + tag), prima di +> Passo 1 di Fase B (setup host Linux Mint). + +> **Tempo stimato**: 1–2 ore (escluso `tar` di backup, che dipende +> dalla dimensione di `F:\CI\`). + +--- + +## Sezione 1 — Salva il baseline pre-migrazione + +Senza un baseline registrato, il confronto richiesto da B7 ("tempo +medio entro ±20% baseline Windows") è impossibile. + +- [ ] Eseguire benchmark sull'host Windows (post Fase A, runner Python attivo): + + ```powershell + cd + .\scripts\Measure-CIBenchmark.ps1 | Tee-Object -FilePath "baseline-windows-$(Get-Date -Format 'yyyyMMdd').txt" + ``` + +- [ ] Annotare in `docs/RUNBOOK.md` (sezione nuova "Windows host baseline"): + - Data + - Tempo medio per job (Windows e Linux template) + - Success rate + - Versione `act_runner` e `ci_orchestrator` (output di `python -m ci_orchestrator --version` se disponibile, altrimenti SHA del commit) + - Hardware: i9-10900X, 64 GB RAM, NVMe SSD (da `AGENTS.md`) + +- [ ] Committare: + + ```powershell + git add docs/RUNBOOK.md + git commit -m "docs(runbook): record Windows host pre-migration baseline" + git push + ``` + +--- + +## Sezione 2 — Pre-requisiti Windows per Fase B + +Tutti questi vanno fatti **prima** di iniziare B1, perché B2/B3/B6 li +presuppongono già pronti. + +### 2.1 Inventario chiavi SSH + +- [ ] Verificare presenza chiavi: + + ```powershell + Get-ChildItem F:\CI\keys\ci_linux* + ``` + + Atteso: `ci_linux` (privata, perm utente owner) e `ci_linux.pub`. Se + mancano, rigenerarle con `ssh-keygen -t ed25519 -f F:\CI\keys\ci_linux -N ""` + e re-installare `ci_linux.pub` nel template `LinuxBuild2404` su + `~ci_build/.ssh/authorized_keys`. + +### 2.2 Recupero password guest Windows (`BuildVMGuest`) + +La password salvata in Windows Credential Manager **non è +esportabile**. Devi conoscerla per re-inserirla con `secret-tool` su +Linux (Passo 3 di Fase B). + +- [ ] Verificare di averla nel password manager personale. +- [ ] Se non la ricordi: bootare il template `WinBuild2025` (e `WinBuild2022`), + resettare la password dell'utente CI (`net user `), + ricatturare snapshot `BaseClean` da stato powered-off (vedi + `AGENTS.md` errore #9), aggiornare il Credential Manager Windows con + la nuova password, e annotarla in modo sicuro. + +### 2.3 Generazione Gitea PAT per il nuovo runner + +- [ ] Aprire Gitea → User Settings → Applications → Generate New Token. +- [ ] Nome: `ci-runner-linux`. Scope: `read:repository` + `write:package` + (o gli stessi del runner Windows attuale). +- [ ] Annotare il token in modo sicuro (verrà inserito al Passo 3 di + Fase B con `secret-tool store ... target GiteaPAT`). + +### 2.4 OpenSSH Server su Windows (per rsync pull dal Linux) + +Necessario solo se al Passo 2 di Fase B (transfer template) preferisci +fare `rsync pull` dal Linux. Alternativa: `rsync push` da Windows con +WSL/Cygwin/MSYS2. + +- [ ] Installare OpenSSH Server: + + ```powershell + Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0 + Start-Service sshd + Set-Service sshd -StartupType Automatic + New-NetFirewallRule -Name sshd -DisplayName 'OpenSSH Server' -Enabled True ` + -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22 + ``` + +- [ ] Validare connessione da un altro host: `ssh user@ "whoami"`. +- [ ] (Opzionale) Configurare `authorized_keys` per il futuro user + `ci-runner` del Linux box. + +### 2.5 Template fully powered-off (gate per B2) + +> AGENTS.md errore #9: snapshot catturato con VM accesa produce +> `*.vmem` / `*.vmsn` che rompono il clone su host diverso. + +- [ ] Verificare che nessun template sia running: + + ```powershell + & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' list + ``` + + Atteso: nessun path sotto `F:\CI\Templates\` nell'output. + +- [ ] Verificare assenza file di runtime: + + ```powershell + Get-ChildItem F:\CI\Templates -Recurse -Include *.vmem,*.vmsn,*.lck + ``` + + Atteso: nessun risultato. Se ci sono `.vmem`/`.vmsn`, lo snapshot + non è clean → ricatturare `BaseClean` / `BaseClean-Linux` da stato + fully powered-off. + +### 2.6 Backup precauzionale di `F:\CI\` + +Da fare **prima** del cutover B6, ma anche prima del transfer B2 è una +buona pratica. + +- [ ] Eseguire backup completo: + + ```powershell + $stamp = Get-Date -Format 'yyyyMMdd' + $archive = "E:\Backup\CI-pre-migration-$stamp.tar" + & 'C:\Program Files\Git\usr\bin\tar.exe' -cf $archive 'F:\CI\' + Get-FileHash $archive -Algorithm SHA256 | Tee-Object "$archive.sha256" + ``` + +- [ ] Verifica integrità (lista contenuto, primi 20 record): + + ```powershell + & 'C:\Program Files\Git\usr\bin\tar.exe' -tf $archive | Select-Object -First 20 + ``` + +- [ ] Annotare path archivio + checksum SHA256. + +### 2.7 Annotare cadenze scheduled task (se custom) + +- [ ] Esportare l'inventario corrente: + + ```powershell + Get-ScheduledTask -TaskName 'CI-*' | + Select-Object TaskName, + @{n='Trigger';e={ $_.Triggers | ForEach-Object { $_.PSObject.Properties | Where-Object Name -in 'StartBoundary','RepetitionInterval','DaysOfWeek' | ForEach-Object { "$($_.Name)=$($_.Value)" } } -join '; ' }}, + @{n='Action'; e={ "$($_.Actions.Execute) $($_.Actions.Arguments)" }} | + Format-List | Tee-Object -FilePath "scheduled-tasks-inventory-$(Get-Date -Format 'yyyyMMdd').txt" + ``` + +- [ ] Confrontare con i `.timer` in `deploy/systemd/`: + + | Task Windows | systemd timer | Cadenza prevista | + | ----------------------------- | ------------------------------------- | ---------------------- | + | `CI-CleanupOrphanedBuildVMs` | `ci-cleanup-orphans.timer` | ogni 6h + boot | + | `CI-Invoke-RetentionPolicy` | `ci-retention-policy.timer` | giornaliero 03:00 | + | `CI-Watch-DiskSpace` | `ci-watch-disk-space.timer` | ogni 15min | + | `CI-Watch-RunnerHealth` | `ci-watch-runner-health.timer` | ogni 15min | + | (nuovo) | `ci-backup-template.timer` | settimanale Dom 02:00 | + +- [ ] Se le cadenze Windows sono diverse, aggiornare gli `OnCalendar` / + `OnUnitActiveSec` in `deploy/systemd/*.timer` **prima** del Passo + 5 di Fase B. Committare la modifica. + +--- + +## Sezione 3 — Logistica e finestra di manutenzione + +Questi non sono comandi, ma checkpoint prima di iniziare B1 e B6. + +- [ ] **Hardware Linux disponibile**: il box target è acquisito, + racked, raggiungibile in rete dall'host Windows e da Gitea. +- [ ] **DNS / IP statico** assegnato al nuovo host Linux (per + registrazione runner + raggiungibilità da admin). +- [ ] **Finestra di manutenzione per cutover B6 concordata**: 30–60 min + di stop Gitea Actions, in un orario a basso traffico. +- [ ] **Comunicazione utenti del repo**: avviso che durante la + finestra B6 i workflow saranno temporaneamente fermi. +- [ ] **Piano di rollback compreso**: rileggere la sezione "Rollback" + del Passo 6 di [PhaseB-user-checklist.md](PhaseB-user-checklist.md). + +--- + +## Tracciamento globale + +| Sezione | Descrizione | Stato | +| ------- | ---------------------------------------------- | ----- | +| 1 | Baseline benchmark salvato in `docs/RUNBOOK.md` | [ ] | +| 2.1 | Chiavi SSH presenti | [ ] | +| 2.2 | Password `BuildVMGuest` recuperata | [ ] | +| 2.3 | Gitea PAT generato per `ci-runner-linux` | [ ] | +| 2.4 | OpenSSH Server attivo (o alt. rsync) | [ ] | +| 2.5 | Template fully powered-off, no `.vmem` | [ ] | +| 2.6 | Backup `F:\CI\` con SHA256 | [ ] | +| 2.7 | Cadenze scheduled task confrontate con timer | [ ] | +| 3 | Hardware + DNS + finestra + comunicazione OK | [ ] | + +Quando tutte le righe sono `[x]`, puoi iniziare il Passo 1 di +[PhaseB-user-checklist.md](PhaseB-user-checklist.md).