local-ci-cd-system/docs/HOST-SETUP.md

Host Setup — Local CI/CD

Procedura di bootstrap della macchina host Windows (i9-10900X, 64 GB RAM, NVMe). Eseguire una volta prima di qualsiasi provisioning del template VM o esecuzione di job CI.

---

Prerequisiti host

Componente	Versione/Note
OS	Windows 11 (host fisico) o Windows Server 2022+
VMware Workstation	Pro 17.x — necessario per vmrun.exe e supporto linked clone
Storage	NVMe dedicato (consigliato F:\ riservato a CI, ≥ 500 GB libero)
RAM	≥ 32 GB (4 VM parallele × 6-8 GB)
Rete	VMnet8 (NAT) configurato in VMware Workstation
PowerShell	5.1+ (built-in) o 7.x
Privilegi	Account amministrativo per Setup-Host.ps1

Software opzionali installati on-demand dallo script:

• NSSM — installazione automatica via Chocolatey se presente; altrimenti install manuale da https://nssm.cc
• CredentialManager module — installato automaticamente (scope CurrentUser)

---

Directory layout

Setup-Host.ps1 crea l'intera struttura sotto $CIRoot (default F:\CI\):

F:\CI\
├── BuildVMs\               # cloni temporanei delle VM build (auto-cleanup post-job)
├── Artifacts\              # output build raccolti dall'host
├── Logs\                   # log per-job (retention: 30 giorni)
├── Templates\
│   ├── WinBuild2025\       # VMX template Windows (immutabile dopo snapshot)
│   └── LinuxBuild2404\     # VMX template Linux Ubuntu 24.04 (immutabile dopo snapshot)
├── keys\
│   ├── ci_linux            # chiave privata SSH per Linux VMs (ed25519, no passphrase)
│   └── ci_linux.pub        # chiave pubblica corrispondente
├── config.toml             # configurazione Python orchestrator (ssh_key_path, ecc.)
├── act_runner\
│   ├── act_runner.exe      # binario runner Gitea
│   ├── config.yaml         # config runner (path, label, capacity)
│   └── logs\               # stdout/stderr del servizio
├── Cache\
│   └── NuGet\              # cache NuGet condivisa via shared folder (§3.1 — DONE 2026-05-10, vedi scripts/Set-TemplateSharedFolders.ps1)
├── RunnerWork\             # working dir di act_runner (job staging)
└── ISO\                    # ISO di installazione (Windows Server 2025, ecc.)

---

Procedura — esecuzione

Step 1 — Clonare il repository

git clone https://gitea.emulab.it/Simone/Local-CI-CD-System.git N:\Code\Workspace\Local-CI-CD-System
cd N:\Code\Workspace\Local-CI-CD-System

Step 2 — Eseguire Setup-Host.ps1 (elevato)

Apri PowerShell come Administrator, poi:

# Esecuzione minimale (crea dirs, archivia credenziali, salta install runner)
.\Setup-Host.ps1 -SkipRunnerInstall

# Setup completo con registrazione runner
.\Setup-Host.ps1 -GiteaRunnerToken 'abc123token'

# CI root su drive diverso
.\Setup-Host.ps1 -CIRoot 'D:\CI' -GiteaRunnerToken 'abc123token'

Cosa fa Setup-Host.ps1 — passo per passo

1. Crea albero directory sotto $CIRoot (vedi layout sopra)
2. Verifica VMware Workstation — controlla presenza di C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe
3. Installa modulo CredentialManager (scope CurrentUser, se non presente)
4. Archivia credenziali guest VM in Windows Credential Manager (target BuildVMGuest)
   • Se non passa -GuestPassword, prompt interattivo (SecureString)
   • Se credenziale già esistente, non sovrascrive — istruzioni per update
5. Copia runner/config.yaml in $CIRoot\act_runner\config.yaml (se non esistente)
6. Installa act_runner come servizio Windows via NSSM:
   • Verifica presenza NSSM in PATH; tenta install via choco install nssm -y
   • Registra runner con Gitea (act_runner register --no-interactive --instance ... --token ... --name local-windows-runner --labels windows-build:host,dotnet:host,msbuild:host) se token fornito
   • Crea servizio: AppDirectory, AppParameters daemon --config <path>, log rotation 10 MB
   • Avvia servizio (SERVICE_AUTO_START)
7. Configura SSH alias gitea-ci in ~/.ssh/config (HostName, Port, User git)

Note operative (scoperte in validazione end-to-end)

Setup-Host.ps1 da solo non basta per la pipeline Python su runner LocalSystem. Dopo Setup-Host:

• Credenziale guest nel vault SYSTEM, username host-qualificato. Lo step 4 scrive in Windows Credential Manager dell'utente interattivo → invisibile ad act_runner (LocalSystem). Esegui (elevato): \.\scripts\Set-CIGuestCredential.ps1 -UserName 'WINBUILD-2025\ci_build'. Bare ci_build viene rifiutato da NTLM (SEC_E_UNKNOWN_CREDENTIALS): usa il computer name del guest (= CN del cert WinRM). Diagnostica: \.\scripts\Test-CIGuestWinRM.ps1 -IpAddress <guest-ip>.
• venv di produzione = install non-editable. Popola F:\CI\python\venv con python -m pip install . dal repo reale — mai pip install -e . (il .pth punta a un path che LocalSystem non risolve → No module named ci_orchestrator). Vedi plans/PhaseA-user-checklist.md Passo 1. Nessun workflow CI deve installare in quel venv (lint usa un venv effimero per-job).
• Gitea app.ini: imposta [actions] DEFAULT_ACTIONS_URL = github e referenzia l'action col URL completo (https://gitea.emulab.it/Simone/local-ci-cd-system/.gitea/actions/local-ci-build@main) così le action GitHub (checkout, upload-artifact) restano risolvibili e l'action locale punta all'istanza. Il repo local-ci-cd-system deve essere pubblico (il runner clona l'action senza autenticazione) e l'action deve esistere su @main (il ref che il runner clona).

---

Parametri principali

Parametro	Default	Note
-CIRoot	F:\CI	Base directory per tutti i dati CI
-GuestCredentialTarget	BuildVMGuest	Target Credential Manager
-GuestUsername	ci_build	Account build dentro la VM
-GuestPassword	(prompt)	Mai hard-codare
-ActRunnerExe	<CIRoot>\act_runner\act_runner.exe	Path binario runner
-ActRunnerConfigYaml	<repo>\runner\config.yaml	Source del config da copiare
-GiteaUrl	http://10.10.20.11:3100	URL Gitea per registrazione
-GiteaRunnerToken	(vuoto)	Token registrazione (Admin → Runners)
-SkipRunnerInstall	$false	Salta installazione servizio
-SkipSSHConfig	$false	Salta scrittura SSH alias
-GiteaSSHHost	10.10.20.11	Hostname SSH Gitea
-GiteaSSHPort	2222	Porta SSH Gitea

---

Post-setup checklist

Allo Setup-Host.ps1 exit 0:

1. Posiziona binario act_runner se non già fatto:

   • Path: F:\CI\act_runner\act_runner.exe
   • Download: https://gitea.com/gitea/act_runner/releases/tag/v1.0.2

2. Posiziona ISO Windows Server 2025 in F:\CI\ISO\ (es. 26100.1742.240906-0331.ge_release_svc_refresh_SERVER_VOL_x64FRE_en-us.iso)

3. Configura host WinRM client (necessario per Prepare-WinBuild2025.ps1):

   # AllowUnencrypted non serve — Prepare usa HTTPS/5986 (nessun testo in chiaro)
   Set-Item WSMan:\localhost\Client\TrustedHosts -Value '192.168.79.*' -Force -Concatenate
   

   Note: Prepare-WinBuild2025.ps1 aggiunge l'IP specifico della VM in modo transitorio e lo ripristina nel finally.

4. Provisiona il template VM Windows — vedi WINDOWS-TEMPLATE-SETUP.md

5. (Opzionale) Genera chiave SSH CI per Linux VMs — necessaria solo se si vuole usare linux-build:

   New-Item -ItemType Directory -Force F:\CI\keys | Out-Null
   ssh-keygen -t ed25519 -f F:\CI\keys\ci_linux -N '""' -C 'ci-linux-runner'
   # Risultato: F:\CI\keys\ci_linux (privata) + F:\CI\keys\ci_linux.pub (pubblica)
   

   Poi provisiona il template VM Linux — vedi LINUX-TEMPLATE-SETUP.md

6. Crea F:\CI\config.toml — necessario affinché il Python orchestrator trovi la chiave SSH e le altre impostazioni:

   Copy-Item N:\Code\Workspace\Local-CI-CD-System\config.example.toml F:\CI\config.toml
   

   Il file config.example.toml contiene già i path corretti per Windows (F:\CI\...). Modificare solo se si usa un $CIRoot diverso da F:\CI.

   Valori chiave configurati:

   Chiave	Valore default	Scopo
   ssh_key_path	F:/CI/keys/ci_linux	Chiave privata per SSH verso Linux guest
   guest_cred_target	BuildVMGuest	Target Windows Credential Manager (WinRM)
   backend.type	workstation	Backend VMware (solo workstation in Phase A)

   Le variabili d'ambiente CI_SSH_KEY_PATH, CI_VMRUN_PATH, CI_GUEST_CRED_TARGET sovrascrivono i valori del TOML se presenti.

7. Registra chiave SSH con Gitea:

   • Gitea UI → User Settings → SSH Keys → Add Key
   • Chiave pubblica: %USERPROFILE%\.ssh\id_rsa.pub

8. Verifica runner online in Gitea:

   • <GiteaUrl>/-/admin/runners
   • Status atteso: Online, label windows-build:host,dotnet:host,msbuild:host

---

Reference Paths

Item	Path / Value
vmrun.exe	C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe
act_runner exe	F:\CI\act_runner\act_runner.exe (servizio: act_runner)
act_runner config	F:\CI\act_runner\config.yaml
act_runner logs	F:\CI\act_runner\logs\ (stdout.log, stderr.log)
Template VMX (Windows)	F:\CI\Templates\WinBuild2025\WinBuild2025.vmx
Template VMX (Linux)	F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx
Snapshot name (Windows)	BaseClean
Snapshot name (Linux)	BaseClean-Linux
SSH key (Linux VMs)	F:\CI\keys\ci_linux (privata), F:\CI\keys\ci_linux.pub
Orchestrator config TOML	F:\CI\config.toml (copia di config.example.toml)
Clone base dir	F:\CI\BuildVMs\
Artifact dir	F:\CI\Artifacts\
Log dir	F:\CI\Logs\ (retention: 30 giorni)
Gitea URL (LAN)	http://10.10.20.11:3100
Gitea URL (ext)	https://gitea.emulab.it
Runner name	local-windows-runner (ID: 1)
Build VM subnet	192.168.79.0/24 (VMnet8 — NAT, internet access per build)
Credential Manager target	BuildVMGuest
Guest username	ci_build

---

Maintenance & operational tasks

Task schedulati (vedi scripts/Register-CIScheduledTasks.ps1 per il bootstrap):

• §2.2 Cleanup VM orfane (scripts/Cleanup-OrphanedBuildVMs.ps1, ogni 6h, -MaxAgeHours 4)
• §2.3 Retention artifact + log (scripts/Invoke-RetentionPolicy.ps1, daily)
• §2.6 Backup template (scripts/Backup-CITemplate.ps1, weekly)
• §2.7 Health check runner (scripts/Watch-RunnerHealth.ps1, ogni 15 min)
• §4.3 Disk space alert (scripts/Watch-DiskSpace.ps1, ogni ora)

---

Troubleshooting

Sintomo	Diagnosi / Fix
vmrun.exe NOT found	Installa VMware Workstation Pro, riesegui
NSSM not available	Install manuale da https://nssm.cc, aggiungi a PATH, riesegui
Runner registration exit != 0	Verifica token Gitea + URL raggiungibile da host
Service act_runner non parte	Check F:\CI\act_runner\logs\stderr.log
New-StoredCredential fail	Verifica modulo CredentialManager importato + scope corretto
Job CI fallisce su Test-WSMan	TrustedHosts host non include subnet VM, AllowUnencrypted=$false
wait-ready SSH: No authentication methods available	F:\CI\config.toml mancante o ssh_key_path non configurato. Crea il file (vedi step 6) oppure passa --ssh-key-path F:\CI\keys\ci_linux