Installare un nodo

Quattro passaggi sulla macchina, e due cose che puoi fare solo tu al di fuori di essa: puntare il DNS, e far verificare la tua impronta.

Il percorso in una riga

Se ti è stato dato un token di arruolamento, l’intero svolgimento dei passaggi da 0 a 2 si comprime in un unico comando. Scarica il codice, lo estrae in /opt/trusted-codes ed esegue tc-operator setup, che recupera operator.yaml di questo nodo dal token, installa lo stack e lo arruola da solo.

curl -fsSL https://app.trusted.codes/download/install-node.sh | sudo bash -s -- <token-di-arruolamento>

Lascia via il token per farti chiedere, così non finisce mai nella cronologia della tua shell:

curl -fsSL https://app.trusted.codes/download/install-node.sh | sudo bash

Il download viene verificato rispetto al manifest di release pubblicato, e il manifest stesso rispetto a una chiave di firma fissata.

Fai invece i passaggi manuali qui sotto se vuoi ispezionare l’archivio prima, fissare una versione, o installare altrove rispetto a /opt/trusted-codes (--dir <percorso>).

Passo 0 — Portare il codice sulla macchina

sudo mkdir -p /opt/trusted-codes
sudo tar -xzf trusted-codes-operator-<versione>.tar.gz -C /opt/trusted-codes
cd /opt/trusted-codes

Il preflight dell’installazione verifica che l’albero sia completo e fallisce rumorosamente, con questa istruzione, se non lo è.

Passo 1 — Modificare operator.yaml

cp scripts/tc-operator/operator.yaml.example operator.yaml
chmod 600 operator.yaml
$EDITOR operator.yaml

Tienilo in modalità 0600 — contiene la tua password SMTP. Due campi sono obbligatori:

home_server: node1.example.com
admin_email: ops@example.com

Tutto il resto ha un valore predefinito funzionante. operator.yaml copre il resto del file.

Passo 2 — Installare

sudo scripts/tc-operator/tc-operator install --config operator.yaml

È idempotente — sicuro da rieseguire, e rieseguirlo è il modo normale per applicare un nuovo archivio. Fa questo:

1. Fa il preflight della macchina: controlla il sistema operativo, provisiona uno swapfile da 4 GB, installa Docker se assente, permette le porte 22, 80 e 443 attraverso il firewall.
2. Genera ogni segreto ed emette il certificato mTLS del nodo.
3. Avvia l’intero stack in un progetto Docker isolato, con ogni porta pubblicata legata a 127.0.0.1.
4. Riproduce lo schema — migrazioni, poi seed di riferimento, poi la sovrascrittura dell’operatore. Un database nuovo costruito per costruzione, mai da un dump.
5. Collega l’identità e i flag di federazione, e attiva la discovery WebFinger.
6. Si autotesta: una lettura autenticata, e l’handler di federazione che risponde.
7. Stampa i record DNS di cui hai bisogno e scrive il payload di ammissione.

Non si interrompe se il tuo DNS non è ancora puntato. Il TLS è un passaggio separato.

L’installazione non è chiusa dietro una conferma digitata: è il tuo unico comando sulla tua stessa macchina.

Scrive /etc/trusted-codes/install.log con l’output completo di ogni comando, e /etc/trusted-codes/README.md — un riferimento sulla macchina che nomina ogni file in quella cartella, quali sono critici per l’identità, che cosa fa ogni container e che cosa si rompe quando è giù. Parti da questi due quando qualcosa sembra sbagliato.

Il tuo primo amministratore

Se hai impostato admin_email, l’installazione crea anche il tuo primo operator_admin per quell’indirizzo e stampa una password temporanea monouso. Accedi all’app di amministrazione del nodo e cambiala subito. L’installer la stampa una sola volta e mai più. Se la perdi prima di averla cambiata, riesegui l’installazione a un terminale: trova l’account esistente e offre di reimpostare la password.

Quel ruolo amministra solo questo nodo. Gli viene negata ogni schermata centrale — concessioni, diritti, piani, feature flag — a livello di server, non solo nell’interfaccia, e non c’è modo di elevarlo. Vedi Gestire il nodo.

Passo 3 — Puntare il DNS, poi finalizzare il TLS

L’installer stampa il record esatto. Impostalo presso il tuo provider DNS:

node1.example.com.  A  <ip-della-tua-macchina>

Una volta che si risolve:

sudo scripts/tc-operator/tc-operator finalize-tls --config operator.yaml

Questo interroga finché il record A non si risolve verso la macchina, compone la configurazione del proxy, e attiva HTTPS con un certificato Let’s Encrypt.

Fai una prova con --dry-run prima. Usa l’ambiente di staging di Let’s Encrypt: il certificato non è affidabile, e non consumi alcun limite di frequenza. Conta, perché il limite di frequenza reale è per dominio e non puoi annullare l’averlo raggiunto.

Passo 4 — Inviare il payload di ammissione

L’installer ha scritto /etc/trusted-codes/admission-payload.json. Contiene solo materiale a chiave pubblica: la tua chiave pubblica di firma federata e la sua impronta, la tua impronta mTLS, i tuoi domini e le tue funzionalità.

scripts/tc-operator/tc-operator submit-admission

Questo firma il payload con la chiave di federazione del tuo nodo e lo invia alla coda di revisione centrale.

La firma dimostra che il tuo nodo possiede la chiave. Non dimostra che tu possieda l’hostname — quindi comunica a Trusted Codes l’impronta della tua chiave pubblica tramite un canale separato. Il comando la stampa. Qualcuno la verifica a mano e poi approva il tuo nodo; non c’è autoapprovazione. Rieseguire il comando aggiorna la voce in sospeso.

Una volta approvato, e una volta ripubblicato il registro firmato, il tuo nodo federa con la mesh. Fino ad allora la superficie di amministrazione resta dietro una schermata “in attesa di approvazione”.

Prima di puntarci utenti reali

Il nodo gira nel momento in cui l’installazione finisce. Non è la stessa cosa che essere pronto.

• I record DNS si risolvono verso la macchina, e finalize-tls ha completato con un certificato valido.
• Ammissione approvata — la tua impronta verificata, il nodo che federa.
• SMTP collegato e verificato. Invia a te stesso un link di accesso e conferma che arriva.
• La password di amministrazione cambiata da quella temporanea.
• /etc/trusted-codes/secrets.env copiato da qualche parte offline. Perderlo perde le chiavi di identità del nodo e rende illeggibile qualsiasi dato ripristinato.
• Chiavi di integrazione opzionali impostate, se vuoi quelle funzioni.

Quando qualcosa fallisce

La build di una superficie è stata saltata. Le altre superfici si sono installate; solo quel portale non è stato compilato. Leggi l’errore in install.log — cerca surface <nome>: building. La causa solita è la memoria: una riga “killed” o segnale 137 significa che la macchina ha finito la memoria. Aggiungi RAM o swap e riesegui l’installazione, che ritenta la build. Il nodo è utilizzabile nel frattempo.

Il TLS non si è finalizzato. Quasi sempre DNS che non si è ancora propagato. Conferma con getent hosts <tuo-dominio>, poi esegui di nuovo finalize-tls.

L’ammissione è bloccata in sospeso. Qualcuno presso Trusted Codes deve verificare la tua impronta fuori banda e approvarla. Reinviare aggiorna la voce; non la approva.