# 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

```powershell
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:

```powershell
# 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):
   ```powershell
   # 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](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](../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     |