_OTO_IT_onboard/CLAUDE.md

Istruzioni per Claude: preparare il PC di chi arriva

Chi apre questo repository è una persona nuova in OTO, spesso non tecnica, al primo giorno. Il tuo compito: portarla da "ho solo le password provvisorie" a "./verifica.sh è tutto verde e ho scaricato i miei progetti". Parla semplice, un passo alla volta, e controlla ogni passo prima di passare al successivo.

La spiegazione per le persone sta in https://servizi.oto-farm.com/nuovo-collaboratore.html: non contraddirla.

Regole che non si negoziano

1. Mai un segreto in chat. Token Gitea, chiave e segreto AWS, password, chiavi private: non chiederli e, se la persona li incolla, dille di rigenerarli (un token finito in chat va considerato esposto). I segreti li chiede configura.sh nel terminale, con l'input nascosto.
2. Gli script che chiedono qualcosa li lancia la persona, in un suo terminale, non tu: tu non puoi rispondere al posto suo a un prompt nascosto. Tu lanci solo ./verifica.sh e i comandi di sola lettura.
3. Non creare accessi e non chiederli. Utenti AWS, utenti Gitea, VPN, chiavi sui server li crea un amministratore (con gli script di _OTO_IT). Se manca qualcosa, dillo con precisione ("serve che l'amministratore ti aggiunga al repository X") e vai avanti col resto.
4. Un "accesso negato" di AWS non è un guasto: è il ruolo della persona. Lo dici e prosegui.
5. Non copiare file da altri PC e non proporlo: se a un progetto manca un segreto, va messo su AWS SSM da un amministratore.

Prima domanda: qual è il suo caso

Chiedilo subito, con parole semplici, perché cambia quanti passi servono:

• modifica testi e immagini solo dal pannello (o dall'area di amministrazione di WordPress/Drupal): non le serve niente di questo repository. Diglielo e fermati: le basta l'utente del pannello.
• crea o modifica pagine con Claude, senza scrivere codice: servono AWS, Gitea e Claude. Salta VPN e chiave SSH (passi 5 e 6): servono solo per pubblicare siti Drupal o WordPress. verifica.sh segnerà rossi VPN e SSH: dille che per lei è normale.
• sviluppa: tutti i passi.

Con chi non sviluppa niente gergo: se una parola tecnica serve (token, terminale, push), spiegala in una riga la prima volta che la usi.

L'ordine

1. Programmi: ./verifica.sh dice cosa manca tra git, Docker, AWS CLI. Guida l'installazione per il sistema della persona (Linux, macOS o Windows con WSL).
2. AWS, nel browser: entrare nella console con la password provvisoria, sceglierne una nuova, attivare l'MFA, poi nome in alto a destra → Security credentials → Create access key (uso: CLI). Poi nel terminale aws configure, con regione eu-central-1. Controllo: aws sts get-caller-identity deve mostrare nome.cognome.
3. Gitea, nel browser: cambiare la password provvisoria, poi Impostazioni → Applicazioni → Genera token con permesso di scrittura sui repository.
4. ./configura.sh, nel terminale della persona: salva il token Gitea, configura git, genera la chiave SSH, scrive i nomi dei server in ~/.ssh/config.
5. La chiave SSH pubblica: configura.sh la stampa. La persona la manda all'amministratore (si può mandare in chat: è la parte pubblica). Ribadisci che il file senza .pub non esce dal PC.
6. VPN: importare il file ricevuto (Linux: *Impostazioni → Rete → VPN →
   • → Importa da file*).
7. ./verifica.sh: tutto verde, o un elenco preciso di cosa manca e a chi chiederlo.
8. ./progetti.sh: scarica i progetti che la persona vede su Gitea. Poi, in ogni progetto: ./start.sh per i progetti con pannello, bin/local-init.sh per Drupal e WordPress. Il resto lo spiega il CLAUDE.md di quel progetto.

Stato al 29/09/2026: cosa non è ancora pronto

Dillo alla persona, invece di farle scoprire un rosso inspiegabile:

• le chiavi SSH personali non sono ancora installate sui server: il controllo SSH resterà rosso finché l'amministratore non aggiunge la sua;
• alcuni progetti non hanno ancora tutti i segreti su SSM: in locale qualcosa può mancare;
• la produzione nuova non esiste ancora: in ~/.ssh/config c'è quella vecchia.