_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 la mail I tuoi accessi OTO che le ha mandato chi amministra (link, utenti, password, la frase per te) e, su LastPass, la chiave AWS e, se sviluppa, la VPN. 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	nella mail I tuoi accessi OTO che le ha mandato chi amministra: righe già pronte da copiare. Se non ce l'ha, risponde a quella mail o 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)	in una nota LastPass condivisa da chi amministra (non nella mail, apposta): 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	è nella mail (nome.cognome); su Gitea lo vede in alto a destra, cliccando l'icona del profilo
Email di lavoro	il suo indirizzo @oto.agency
File e credenziali della VPN	in una nota LastPass condivisa da chi amministra: il file .ovpn è allegato alla nota (Attachments → si scarica, finisce in Download), utente e password della VPN sono scritti nella nota. Il programma è OpenVPN Connect, lo installi tu. Se la nota non c'è, 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 e, per chi sviluppa, OpenVPNTechnologies.OpenVPNConnect. 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 (per chi sviluppa anche brew install --cask openvpn-connect).
   • 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 della mail 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 della mail 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à nella nota LastPass. 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 la nota 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). OpenVPN Connect l'hai già installato tu; lei, un passo alla volta: apre la nota VPN su LastPass e scarica il file .ovpn allegato; apre OpenVPN Connect → Upload File (o Import Profile → File) → Browse → il file in Download; scrive utente e password della VPN dalla stessa nota, spunta Save password, Connect. È accesa quando l'interruttore diventa verde (Connected).
6. Dirlo all'amministratore: risponde alla mail I tuoi accessi OTO scrivendo «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.