_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`.