ThothII/docs/install/publishing-images.md

Pubblicare immagini e pacchetto operatore / Publish images and operator bundle

Italiano

Questo comando è riservato al manutentore. L'utente finale scarica il pacchetto e le immagini già compilati. La prima prerelease riguarda Linux amd64, utilizzato da Ubuntu WSL2 su Windows e successivamente da Omarchy; non certifica ancora il percorso completo di installazione o i collaudi manuali.

Prerequisiti del manutentore: Git, Node 24/npm, Go indicato in tools/tht/go.mod, Docker con Buildx e capacità di eseguire Linux amd64, tar. Bun viene installato dal lock npm e serve soltanto per compilare il pacchetto. Il commit da pubblicare deve essere già disponibile sul repository Gitea pubblico.

1. Eseguire docker login sul computer di pubblicazione con un account autorizzato a creare repository pubblici e pubblicare immagini nel namespace scelto. Usare un credential store Docker: il token non va passato sulla riga di comando, scritto nel repository o copiato nel pacchetto.
2. Predisporre nel credential helper Git l'accesso al repository Gitea con diritto di creare rilasci e allegati. Il comando riusa quelle credenziali senza stamparle.
3. Installare le dipendenze del produttore con cd backend && npm ci, poi eseguire:

node scripts/publish-installation.mjs \
  --revision COMMIT_GIA_PUBBLICATO \
  --version 0.1.0-install-preview.1 \
  --namespace tylconsulting \
  --platforms linux/amd64 \
  --output /percorso/privato/rilascio-0.1.0-install-preview.1

La directory di output deve essere nuova o vuota e avere un genitore esistente. Diventa privata e contiene stato di ripresa, log del produttore, archivi e checksum. Non è una directory di installazione. Il produttore usa un worktree temporaneo al commit richiesto, così modifiche locali, segreti e workspace non entrano nelle build.

Il comando prepara tylconsulting/thothii-core e tylconsulting/thothii-frontend come repository pubblici, costruisce e pubblica le immagini versionate, risolve i digest di tutte le immagini e crea gli archivi del comando nativo con Compose e risorse di inizializzazione. Catalog migration e workspace maintenance usano lo stesso digest core. PostgreSQL, Qdrant e Ollama restano immagini upstream.

Prima di rendere pubblico il rilascio Gitea, vengono verificati pull anonimi delle immagini, smoke test senza rete di core/frontend, checksum e download degli allegati. Una build o un upload incompleto lascia il rilascio in bozza. Per riprovare, rieseguire lo stesso comando con gli stessi parametri e la stessa directory. Immagini già presenti devono appartenere allo stesso commit/versione; allegati esistenti devono avere lo stesso checksum. Il produttore non sostituisce versioni pubblicate con contenuti diversi. Conservare la directory fino al completamento.

Il risultato pubblico comprende thothii-VERSION-linux-amd64.tar.gz e SHA256SUMS.txt. L'archivio contiene bin/tht, il validatore affiancato, release-manifest.json, Compose, SQL/script di inizializzazione e guide. Non contiene credenziali, dati dei workspace o database di esempio. La verifica su questa macchina di pubblicazione non sostituisce il successivo collaudo Windows.

English

This is a maintainer command. Consumers download precompiled images and the native operator bundle. The first prerelease targets Linux amd64 for Ubuntu WSL2 and later Omarchy; full installation and real-host acceptance remain separate work.

The maintainer needs Git, Node 24/npm, the Go toolchain from tools/tht/go.mod, Docker Buildx with Linux amd64 execution support, and tar. The npm lock supplies Bun for producer builds only. Push the selected source commit to the public Gitea repository before publication. Use Docker's credential store for docker login and Git's credential helper for Gitea release/attachment permissions. Never pass tokens as command arguments or include them in a checkout or archive.

From backend, run npm ci, then the command above with an explicit revision, version, namespace, platforms and a new private output directory. A temporary Git worktree isolates the selected commit. The producer publishes core/frontend to Docker Hub and retains PostgreSQL, Qdrant and Ollama upstream. All runtime and maintenance services use resolved immutable platform digests.

The Gitea release stays a draft until images, anonymous pulls, network-isolated smoke checks and uploaded bundle checksums pass. An interrupted run can be retried with the same arguments and output directory. Existing images must match the source/version, and existing attachments must match their checksum; published versions are not overwritten. Producer logs and retry state stay local.

Download the matching .tar.gz and SHA256SUMS.txt from the public Gitea prerelease, verify the archive checksum, then extract it. Keep the two executables together. The bundle needs no application checkout, Node, Bun, Python or compiler on the consumer host. It carries the manifest, Compose and initialization assets, but no installation credentials, workspace data or example databases. Linux arm64 can be selected explicitly for later release work; it does not imply macOS acceptance.

Developer regression checks:

cd backend
node --test scripts/release-*.test.mjs