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\
│   └── WinBuild\           # VMX template Windows (immutabile dopo snapshot)
├── 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 (TODO §3.1)
├── 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)

---

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 — vedi WINDOWS-TEMPLATE-SETUP.md

5. Registra chiave SSH con Gitea:

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

6. 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	F:\CI\Templates\WinBuild\CI-WinBuild.vmx
Snapshot name	BaseClean
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

Voci di backlog (vedi TODO.md):

• §2.2 Cleanup VM orfane schedulato (scripts/Cleanup-OrphanedBuildVMs.ps1 ogni 6h, -MaxAgeHours 4)
• §2.3 Retention artifact + log (Artifacts > 30 gg, Logs > 30 gg, guard libero < 50 GB)
• §2.7 Health check runner (query API Gitea ogni 15 min, restart su offline)
• §4.3 Disk space alert (F: < 50 GB → eventcreate/webhook)
• §1.2 Restringere TrustedHosts da * a 192.168.79.*

---

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