_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, utente, email, la frase per te, nessuna password) e, su LastPass, due schede condivise con lei: AWS > Nome Cognome (console, MFA e, nel campo di testo, la chiave di accesso) e Gitea > nome.cognome (password Gitea), più la scheda OTO > VPN HK nome.cognome se le serve 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: scrivere i propri segreti nel terminale e, se le serve, accendere la VPN. 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), e dalle il comando completo, da copiare così com'è: cd nel percorso vero della cartella su quel PC (quello in cui l'hai scaricata, che conosci solo tu: la pagina per le persone non lo scrive apposta) e ./configura.sh, in un blocco di codice, per esempio cd "/c/Users/mario/oto/_OTO_IT_onboard" && ./configura.sh. Su Windows il percorso va nella forma di Git Bash (/c/Users/...), non C:\.... 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. Dove scaricare lo chiedi sempre, prima di scaricare. Questo repository e i progetti vanno nella cartella che sceglie la persona, non in una che decidi tu: non esiste un posto di default (fino al 13/10/2026 le istruzioni dicevano ~/Work/workspace/oto, che era la cartella di chi le ha scritte). Chiedile in quale cartella vuole i progetti, proponendo al massimo un esempio (sotto la sua cartella utente), e usa quella. Se l'ha già scelta per questo repository, chiedile se i progetti vanno accanto a lui, e non darlo per scontato.
7. 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
Utente Gitea ed email	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
Password Gitea	su LastPass, scheda Gitea > nome.cognome (per esempio Gitea > sara.locatelli), campo Password. Nella mail non c'è, apposta
Indirizzo, utente, password e codice a due fattori della console AWS	su LastPass, scheda AWS > Nome Cognome (nome per esteso: AWS > Sara Locatelli). Il primo giorno non servono
Chiave di accesso AWS (Access key ID e Secret access key)	su LastPass, scheda AWS > Nome Cognome, nel campo di testo: due righe, Access key ID (inizia con AKIA) e Secret access key. Nella mail non c'è, 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	nella scheda LastPass OTO > VPN HK nome.cognome condivisa da chi amministra: il file .ovpn è allegato alla scheda (Attachments → si scarica, finisce in Download), utente e password della VPN sono scritti nella scheda. Il programma è OpenVPN Connect, lo installi tu. Se la scheda 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.

Non le chiedi che lavoro fa

Lo ha già deciso chi amministra (deciso il 07/10/2026): se la persona ha la mail, le servono tutti i passi; se su LastPass ha anche la scheda OTO > VPN HK nome.cognome, le serve anche la VPN. Chi lavora solo dal pannello del sito non riceve la mail e non arriva qui. Alla VPN (passo 5) le chiedi soltanto se fra le schede LastPass condivise con lei c'è OTO > VPN HK nome.cognome: se no, salti il passo, e lanci ./verifica.sh --senza-vpn: staging non raggiungibile diventa giallo invece che rosso, e il risultato può essere tutto a posto.

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)". Homebrew non si mette da solo nel PATH (sui Mac Apple Silicon sta in /opt/homebrew): senza, in un terminale nuovo brew e aws non si trovano. Lo aggiungi tu, una volta: echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile (su un Mac Intel sta in /usr/local e il passo non serve). Poi tu: eval "$(/opt/homebrew/bin/brew shellenv)" && brew install git awscli e brew install --cask docker. Se un'installazione --cask chiede la password del Mac, la lancia la persona nel Terminale. Gli script di questo repository trovano brew anche senza il PATH sistemato, il terminale della persona no.
   • 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. Prima le chiedi dove metterlo (regola 6), poi: git clone https://git.oto-farm.com/admin/_OTO_IT_onboard.git "<cartella scelta>/_OTO_IT_onboard" (è pubblico, non ha segreti) e da lì continui.
3. Niente login su AWS né su Gitea nel browser (deciso il 07/10/2026): le password sono già le definitive e l'MFA di AWS lo attiva chi amministra, con il seme nella scheda LastPass AWS > Nome Cognome. La chiave di accesso non la crea: è già nel campo di testo di quella scheda. Solo se lì non c'è, la crea dalla console AWS (percorso nella tabella qui sopra), entrando con utente, password e codice a due fattori della stessa scheda.
4. ./configura.sh, nel terminale della persona. Chiede utente e password di Gitea (l'utente dalla mail, la password dalla scheda Gitea > nome.cognome) e poi i due pezzi della chiave AWS, che lei copia dal campo di testo della scheda AWS > Nome Cognome; 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 e le loro chiavi in ~/.ssh/known_hosts (da server.known_hosts). La chiave la crea come ~/.ssh/oto_ed25519 e la collega anche ai due nomi con cui la cercano i deploy dei progetti, oto_staging_ed25519 e oto_production_ed25519 (un file che c'è già con quel nome non lo tocca). Esce con errore se un passo non è riuscito, e lo dice in rosso: allora non si va avanti. 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 se su LastPass ha la scheda OTO > VPN HK nome.cognome (chiediglielo). Prima va installato OpenVPN Connect: su Windows lo installi tu, winget install -e --id OpenVPNTechnologies.OpenVPNConnect; su Mac brew install --cask openvpn-connect chiede la password del Mac (installa un componente di sistema), quindi lo lancia la persona nel Terminale e tu le dai il comando. Poi lei, un passo alla volta: apre la scheda 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 scheda, 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 (--senza-vpn se non ha la VPN): tutto verde, o un elenco preciso di cosa manca e a chi chiederlo. Controlla anche che git entri su Gitea con il token giusto e che la chiave AWS sia la sua nell'account di OTO, non solo un utente con lo stesso nome.
8. ./progetti.sh: scarica i progetti che la persona vede su Gitea. Prima le chiedi in quale cartella (regola 6), poi lo lanci tu con la cartella e i nomi: ./progetti.sh --in "<cartella scelta>" nome1 nome2. Senza --in lo script non scarica niente: un posto di default non c'è apposta. 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. Giallo vuol dire solo "il server non accetta la tua chiave": se una riga è rossa il ruolo non c'entra, e verifica.sh dice cosa fare (di solito rilanciare configura.sh, che registra le chiavi dei server). Se ssh chiede Are you sure you want to continue connecting?, non far rispondere yes alla cieca: le chiavi giuste sono in server.known_hosts, e le registra configura.sh.