_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 il messaggio di benvenuto che l'amministratore le ha condiviso su LastPass: password e chiave AWS. 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.
6. Ogni volta che le chiedi qualcosa, le dici dove lo trova o dove lo crea. Non "inserisci la chiave AWS", ma "la crei nella console AWS: il tuo nome in alto a destra → Security credentials → …". Indirizzo, menu e pulsante, con i nomi come li vede sullo schermo (in inglese, se la pagina è in inglese). Se lei non trova un pulsante, chiedile cosa vede invece di ripetere lo stesso percorso. Dove sta ogni cosa è nella tabella qui sotto: se le chiedi qualcosa che non c'è, prima trova dove si prende e aggiungilo alla tabella.

Cosa le chiedi e dove lo trova

Cosa	Dove lo trova o lo crea
Indirizzo, utente e password di AWS e di Gitea	nel messaggio di benvenuto: una nota che chi amministra le ha condiviso su LastPass. Se non ce l'ha, lo chiede a lui: tu non puoi recuperarlo
Codice dal telefono (MFA) di AWS	console AWS → il suo nome in alto a destra → Security credentials → riquadro Multi-factor authentication (MFA) → Assign MFA device → Authenticator app. Serve un'app di autenticazione sul telefono (Google Authenticator, Microsoft Authenticator o simili): se non ce l'ha, prima la installa dallo store
Chiave di accesso AWS (Access key ID e Secret access key)	nel messaggio di benvenuto su LastPass: la crea chi amministra insieme all'utente. Solo se lì non c'è (è arrivata prima, o la chiave è stata cancellata), la crea lei: console AWS → il suo nome in alto a destra → Security credentials → riquadro Access keys → Create access key → Command Line Interface (CLI) → spunta la conferma → Next → Create access key. I due pezzi sono nella pagina Retrieve access keys; la Secret si vede con Show, una volta sola. Se l'ha chiusa: cancella quella chiave dallo stesso riquadro e ne crea un'altra
Utente Gitea	è quello del messaggio di benvenuto (nome.cognome); su Gitea lo vede in alto a destra, cliccando l'icona del profilo
Email di lavoro	il suo indirizzo @oto.agency
File della VPN	lo manda chi amministra, che lo riceve dal fornitore. Il programma da installare dipende dal file: .ovpn → OpenVPN Connect, .conf → WireGuard. Se il file non le è arrivato, lo chiede a chi amministra
Password del Mac (per Homebrew)	è quella con cui accende il Mac
Accesso a un progetto che non vede su Gitea	lo dà chi amministra: dille il nome del progetto da chiedere

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. Il login su AWS nel browser, lo fa lei. Le password del messaggio di benvenuto sono già le definitive (dal 07/10/2026): né AWS né Gitea chiedono di cambiarle, e su Gitea dal browser non c'è niente da fare.
   • AWS: entrare dall'indirizzo del messaggio di benvenuto (IAM user, utente e password) e attivare l'MFA. I percorsi esatti sono nella tabella qui sopra: dàglieli un passo alla volta. La chiave di accesso non la crea: è già nel messaggio di benvenuto. Se lì non c'è, la crea adesso, e lascia aperta la pagina: la parte segreta si vede una volta sola.
4. ./configura.sh, nel terminale della persona. Chiede utente e password di Gitea e poi i due pezzi della chiave AWS, che lei copia dal messaggio di benvenuto su LastPass; 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. Gitea viene prima apposta: è lui a dire chi è la persona. Se sul PC c'è già una chiave AWS di un altro (rimasta da chi lo usava, o copiata da un collega), lo script lo dice e chiede la sua: dille di avvisare l'amministratore, perché quella chiave va disattivata. Una chiave altrui non va mai tenuta "intanto che funziona": tutto quello che la persona fa su AWS risulterebbe fatto dall'altro.
5. VPN (solo chi sviluppa): installare il programma giusto per il file (vedi tabella) e aprirci dentro il file che le ha mandato chi amministra.
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;
• le produzioni sono due finché i siti non sono migrati tutti: in ~/.ssh/config ci sono oto-production (la macchina nuova, dietro la VPN come staging, utente admin.produzione) e oto-production-old (quella dove girano ancora i siti). Chi ha il ruolo di rilascio entra in tutte e due; per gli altri sono gialle tutte e due, ed è normale.