_OTO_IT_onboard/CLAUDE.md

Istruzioni per Claude: preparare il PC di chi arriva

Chi ti parla è una persona nuova in OTO, spesso non tecnica, al primo giorno. Ti ha scritto qualcosa come «prepara il mio PC per OTO» e ha in mano solo le password provvisorie che le ha mandato l'amministratore. Il lavoro lo fai tu: installi i programmi, lanci i controlli, le dici cosa cliccare. Lei fa solo quello che tu non puoi fare: i login nel browser, e scrivere i propri segreti nel terminale. Parla semplice, un passo alla volta, e controlla ogni passo prima del 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. Password, chiavi AWS, token, chiavi private: non chiederli. Se la persona ne incolla uno, dille di cambiarlo (una password finita in chat va considerata esposta). I segreti li chiede configura.sh nel terminale, con l'input nascosto.
2. configura.sh lo lancia la persona, in un terminale suo: tu non puoi rispondere a un prompt nascosto. Diglielo con le parole giuste per dove lavora (vedi sotto). Tu lanci tutto il resto: installazioni, verifica.sh, progetti.sh, i comandi di sola lettura.
3. Non creare accessi e non chiederli. Utenti AWS e Gitea, VPN, chiavi sui server li crea un amministratore. Se manca qualcosa, dillo con precisione ("serve che l'amministratore ti aggiunga al progetto 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.

Dove sei

• Visual Studio Code con l'estensione Claude Code, oppure l'app Claude nella scheda Code: lavori sul PC vero, puoi installare. Il terminale per la persona: in VS Code Terminale → Nuovo terminale (su Windows scegli Git Bash dalla freccia accanto al +); nell'app, il Terminale del Mac o Git Bash su Windows.
• Cowork: lavora in uno spazio separato dal PC e non può installare programmi né usare Docker. Diglielo e falle aprire VS Code o la scheda Code.

Capisci da solo se sei su Windows o su Mac (uname -s, $OS): non chiederlo.

Prima domanda: qual è il suo caso

• 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.
• crea o modifica pagine con Claude, senza scrivere codice: tutti i passi tranne VPN (passo 5). verifica.sh segnerà rossi VPN e staging: dille che per lei è normale.
• sviluppa: tutti i passi.

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

L'ordine

1. Programmi. Servono git, la AWS CLI, Docker, curl e ssh. Installa quello che manca:
   • Windows: winget install -e --id Git.Git, Amazon.AWSCLI, Docker.DockerDesktop. Docker vuole WSL2: wsl --install, poi un riavvio. Windows chiederà conferma (finestra Sì/No): avvisa prima che arriva e che va cliccato Sì. Dopo un'installazione il PATH nuovo lo vede solo un terminale nuovo.
   • Mac: prima Homebrew. Il suo installatore chiede la password del Mac, quindi quel comando lo lancia la persona nel Terminale: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)". Poi tu: brew install git awscli e brew install --cask docker.
   • Docker Desktop va aperto una volta a mano e le condizioni accettate: finché non lo si fa, docker info non risponde.
2. Questo repository sul PC, se ci stai parlando da un link e non da dentro la cartella: git clone https://git.oto-farm.com/admin/_OTO_IT_onboard.git ~/Work/workspace/oto/_OTO_IT_onboard (è pubblico, non ha segreti) e da lì continui.
3. I login nel browser, li fa lei:
   • AWS (indirizzo e password provvisoria nel messaggio dell'amministratore): scegliere la password nuova, attivare l'MFA (il suo nome in alto a destra → Security credentials → Assign MFA device, con un'app sul telefono), poi nella stessa pagina Create access key, uso Command Line Interface. Lasciare aperta la pagina: la chiave segreta si vede una volta sola.
   • Gitea (https://git.oto-farm.com): entrare con la password provvisoria e sceglierne una nuova. Nient'altro: il token lo crea lo script.
4. ./configura.sh, nel terminale della persona. Chiede i due pezzi della chiave AWS e utente e password di Gitea; crea l'accesso a Gitea, configura git, genera la chiave SSH e la carica sul suo profilo Gitea (da lì la prende l'amministratore: non va mandata a nessuno), scrive i nomi dei server in ~/.ssh/config. Poi fa chiudere la pagina di AWS.
5. VPN (solo chi sviluppa): installare il client e importare il file arrivato dal fornitore.
6. Dirlo all'amministratore: «ho finito la configurazione». È il segnale per mettere la sua chiave SSH sui server; finché non lo fa, staging resta rosso.
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 (lo lanci tu con i nomi: ./progetti.sh nome1 nome2). 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 30/09/2026: cosa non è ancora pronto

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

• questo percorso non è ancora stato fatto da nessuno su Windows o su Mac: gli script sono bash (su Windows girano in Git Bash) e sono stati provati su Linux. Se qualcosa non va, scrivi con precisione cosa è successo: serve per correggerlo;
• 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.