Encelado/Encelado/build/README.md

Catena di verifica, pacchetto e rilascio

Tutto quello che serve a controllare, impacchettare e pubblicare Encelado sta in questa cartella. La radice del progetto contiene solo la Dockerfile e la docker-compose.yml.

È la stessa catena di Mimante/AutoBidder, adattata a una soluzione con più progetti e a un pacchetto che è un'immagine Docker (dalla 5.0, ADR-0008). Le differenze sono segnate sul posto in Release.proj:

	AutoBidder	Encelado
Dove sta la versione	AutoBidder.csproj	Directory.Build.props, ereditato da tutti i progetti
Cosa produce dotnet publish	un eseguibile unico	una cartella framework-dependent: la stessa che il Dockerfile mette in /app
Il pacchetto	installatore Inno Setup	immagine Docker 192.168.30.23:3000/alby96/encelado:<versione> (+ :latest)
Allegati della release	.exe e installatore	zip portabile e template Unraid
Cosa rigioca Backtest	i dossier delle aste	barre M15 bid/ask dei basket (+ learn sul ledger)

File	Cos'è
Release.proj	La catena. Un solo file MSBuild, nessuno script.
gitea.example.json	Modello per gitea.json (che è escluso dal controllo di versione).

Da VS Code

Terminale ▸ Esegui attività…

Attività	Cosa fa
verifica	Compila e lancia i test.
backtest	Ricerca sui basket: ticks, baskets, falsify, learn.
immagine docker	Costruisce l'immagine (i test girano dentro la build). Non pubblica.
pacchetto	Verifica, cartella portabile, immagine, tag a pacchetto pronto. Non tocca Gitea.
rilascia su Gitea	Tutto quanto sopra, più push dell'immagine sul registro di Gitea e release con gli allegati.
docker compose up	Il container in locale con le cartelle di deploy/local/.

Da riga di comando

dotnet msbuild build/Release.proj -t:Verifica
dotnet msbuild build/Release.proj -t:Docker
dotnet msbuild build/Release.proj -t:Pacchetto
dotnet msbuild build/Release.proj -t:Rilascia -p:Versione=5.0.0 -p:Note="Cosa cambia"

# La ricerca sui basket: barre M15 in data/market (da `ticks`), tabelle in results/ e reports/
dotnet msbuild build/Release.proj -t:Backtest -p:Dati="%USERPROFILE%\Documents\Encelado\data\market"
dotnet msbuild build/Release.proj -t:Backtest -p:Dati="..." -p:Comando=falsify -p:Extra="--costs api"
dotnet msbuild build/Release.proj -t:Backtest -p:Dati="A:\Download\Trading" -p:Comando=ticks
dotnet msbuild build/Release.proj -t:Backtest -p:Dati="%USERPROFILE%\Documents\Encelado\data" -p:Comando=learn

Proprietà	Predefinito	A cosa serve
Versione	vuoto	Vuoto = incrementa la minor (5.0.0 → 5.1.0). Altrimenti la scrive, se ha la forma X.Y.Z.
Note	vuoto	Note di rilascio (meglio via ENCELADO_NOTE, vedi sotto).
Immagine	192.168.30.23:3000/alby96/encelado	Nome completo dell'immagine.
SaltaVerifica	false	Non rieseguire i test (girano comunque dentro docker build).
SaltaDocker	false	Solo lo zip portabile, niente immagine né push.
Sovrascrivi	false	Sostituisci una release Gitea con lo stesso tag.
Bozza	false	Crea la release come bozza.
ConsentiModifiche	false	Tagga anche con l'albero sporco. Serve saperlo.
Dati	—	La cartella dei dati. Obbligatoria per Backtest.
Comando	baskets	ticks, baskets, falsify, learn.
Extra	vuoto	Altre opzioni passate allo strumento così come sono, es. --costs api --quick.

Cosa succede in Rilascia

1. ConfigGitea: legge url, owner, repo e token (ambiente o gitea.json); senza, si ferma prima di compilare.
2. Verifica: dotnet test nella cartella di verifica (%TEMP%\Encelado.Verifica).
3. Pubblica: dotnet publish framework-dependent di Encelado.Server in bin/publish/portable, con la versione da riga di comando; controlli su Encelado.Server.dll, config/encelado.json e sull'assenza di sorgenti.
4. Docker: docker build --pull con VERSION e GIT_COMMIT come build-arg; l'immagine ha i tag :<versione> e :latest. La Dockerfile esegue i test nel suo stadio test.
5. Pacchetto: zip portabile bin/installer/Encelado_<v>_portabile.zip, copia del template deploy/unraid/encelado.xml con la versione nel nome, tag v<versione> (solo ora, a pacchetto pronto, e solo con l'albero pulito).
6. Rilascia: git push --tags e verifica che il tag sia sul remoto; docker login sul registro di Gitea con il token (via stdin), docker push dei due tag, docker logout; release su Gitea con lo zip e il template allegati.

Gitea Actions

.gitea/workflows/ci.yml (build + test + docker build a ogni push) e release.yml (immagine sul registro e release a ogni tag v*) fanno sul server quello che Verifica e Rilascia fanno dal PC. Richiedono un runner registrato e il segreto REGISTRY_TOKEN: vedi docs/DOCKER.md, «Gitea Actions». La catena resta il percorso di riferimento finché il runner non c'è.

Chi chiede la versione

MSBuild non può chiedere niente a nessuno: è un motore di compilazione. La domanda la fa l'attività di VS Code (inputs in .vscode/tasks.json) e passa la risposta in -p:Versione=. Lasciando il campo vuoto si prende la minor successiva, che è il caso normale di fine sessione.

La versione arriva dal tag e non viene scritta da nessuna parte. dotnet publish e docker build la ricevono come proprietà da riga di comando, che è globale e vince su quella dichiarata in Directory.Build.props. Tag, assembly, immagine e release portano quindi lo stesso numero per costruzione. Il commit e la data di build finiscono in AssemblyMetadata (Impostazioni ▸ Informazioni, /api/info).

Il tag si crea in fondo, quando lo zip e l'immagine esistono davvero. Il contrario sembra più naturale — decidi il numero, poi costruisci — ma lascia dietro un tag quando la verifica fallisce, e il tentativo dopo riparte da lì.

Gitea

Servono quattro valori. Le variabili d'ambiente hanno la precedenza sul file, così una macchina condivisa può rilasciare senza scrivere un token su disco:

• GITEA_URL, GITEA_OWNER, GITEA_REPO, GITEA_TOKEN
• oppure build/gitea.json, copiato da gitea.example.json

Il token si crea in Gitea da Impostazioni ▸ Applicazioni ▸ Genera nuovo token, con i permessi repository: read and write e package: read and write (serve per il registro dei container). Il registro è lo stesso host di Gitea senza schema (192.168.30.23:3000): in HTTP va dichiarato insecure-registry a Docker Desktop (Settings ▸ Docker Engine).

Il token non passa mai dalla riga di comando: sta in un file di configurazione di curl e in un file letto da docker login --password-stdin, entrambi cancellati subito dopo. Gli Exec hanno EchoOff perché un registro di compilazione è la classica cosa che si incolla in una chat.

Una trappola già pagata

dotnet test e dotnet publish lanciati da dentro MSBuild ereditano l'ambiente del processo padre: MSBUILD_EXE_PATH e MSBuildLoadMicrosoftTargetsReadOnly puntate al build in corso confondono il figlio. Gli Exec azzerano solo quelle due: la ricetta che gira in rete azzera anche MSBuildExtensionsPath e MSBuildSDKsPath, e così il figlio perde la posizione dell'SDK.

I test girano in una cartella a parte (--artifacts-path) perché un server lasciato acceso da VS Code tiene bloccata Encelado.Server.dll nella bin/ di lavoro.

Prerequisiti

• .NET SDK 10
• Docker Desktop (o un demone Docker raggiungibile) per Docker, Pacchetto, Rilascia; -p:SaltaDocker=true per farne a meno
• curl e git, entrambi di serie in Windows 11