Skip to content
Mariano Rodrigo

Mariano Rodrigo

AI Solutions Engineer building production systems with artificial intelligence, automation, and full-stack architecture. This is my public engineering lab: architecture decisions, implementation reports, experiments, and lessons from real systems.

Da una cartella vuota a un sito web online: guida completa per principianti

· ai-systems, tooling, web

Il riepilogo in un minuto

Preferisci guardarlo? Ecco l’intero manuale in un unico video guidato, narrato dall’inizio alla fine, con ogni schermata dei provider animata (sottotitoli in inglese):

Il corso completo di 24 passi, narrato

Dominio, Cloudflare, GitHub, Claude Code e Vercel, da zero alla produzione.

Questo è un manuale completo da seguire passo passo, pensato per chi parte da zero. Ogni passo ha il comando esatto, un Checkpoint che ti dice cosa dovresti vedere e, dove le persone si bloccano di solito, una nota Se fallisce. Un agente IA (Claude Code) fa il lavoro deterministico: scaffolding, Git, deploy. Tu tieni gli account, le decisioni e la verifica.

In tutto il manuale, sostituisci example.com con il tuo dominio reale e username con il tuo vero username GitHub. Non saltare un checkpoint. Se un comando non viene riconosciuto o un output sembra sbagliato, fermati e sistemalo prima di andare avanti.

Una nota sui termini: un terminale è l’app di testo dove scrivi i comandi. Su macOS apri Terminal; su Windows usa PowerShell o Windows Terminal; su Linux usa la tua app di terminale. Più avanti, VS Code ha il suo terminale integrato.

Fase 1 · Il dominio e il DNS

Passo 1: Compra un dominio

Compra un dominio da Hostinger o da un qualsiasi registrar, per esempio example.com. Mantieni l’accesso all’account del registrar: cambierai i suoi nameserver al passo successivo.

Checkpoint. Puoi aprire il pannello di gestione del dominio dal tuo registrar.

Passo 2: Crea un account Cloudflare

Crea un account Cloudflare gratuito, poi: accedi, scegli Add a domain, inserisci il dominio del Passo 1 e scegli il piano Free. Continua finché Cloudflare mostra due nameserver assegnati, simili a:

ada.ns.cloudflare.com
bob.ns.cloudflare.com

Checkpoint. Cloudflare mostra due nameserver assegnati al tuo dominio.

Passo 3: Collega il dominio a Cloudflare

Nel pannello del dominio del registrar, trova la configurazione dei nameserver e sostituisci quelli attuali con i due di Cloudflare. Salva.

Cosa fa. I nameserver dicono a internet quale provider DNS è autoritativo per il tuo dominio. Dopo questo cambio, Cloudflare diventa il posto dove gestisci i record DNS del dominio.

Checkpoint. Di nuovo in Cloudflare, lo stato del dominio diventa Active. Non continuare finché non lo fa (può richiedere da minuti a ore).

Fase 2 · Account

Passo 4: Crea un account GitHub

Crea un account GitHub, verifica l’email e accedi. Annota il tuo username GitHub, lo userai spesso.

Checkpoint. Email verificata, dashboard GitHub accessibile, username salvato.

Passo 5: Crea un account Vercel

Crea un account Vercel con Log in with GitHub, e autorizza Vercel ad accedere all’account GitHub del Passo 4. Non creare ancora il progetto.

Checkpoint. Il tuo account Vercel è collegato a GitHub.

Fase 3 · Strumenti locali

Passo 6: Installa Visual Studio Code

Scarica e installa Visual Studio Code dal sito ufficiale (macOS, Windows o Linux). Aprilo una volta per confermare che parte, poi chiudilo.

Se sei su macOS. Abilita il comando code che userai dopo: apri VS Code, premi Cmd+Shift+P, scrivi Shell Command: Install 'code' command in PATH ed eseguilo.

Checkpoint. VS Code si apre correttamente.

Passo 7: Installa Git

Installa Git (macOS: xcode-select --install o l’installer ufficiale; Windows: Git for Windows; Linux: il tuo package manager). Poi, in un terminale:

git --version

Checkpoint. Stampa una versione, per esempio git version 2.50.0. Non continuare se il comando non viene riconosciuto.

Passo 8: Installa Claude Code

Installa Claude Code seguendo le istruzioni ufficiali per il tuo sistema operativo, poi verifica:

claude --version

Checkpoint. Stampa la versione installata. Non continuare finché Claude Code non parte correttamente.

Fase 4 · Identità Git e accesso a GitHub

Passo 9: Configura la tua identità Git

Imposta il nome e l’email che Git allega ai tuoi commit. Usa la stessa email del tuo account GitHub:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Cosa fa. Ogni commit porta questa identità. Che l’email coincida con il tuo account GitHub è ciò che collega i tuoi commit al tuo profilo.

Checkpoint. Questi stampano i valori appena impostati:

git config --global user.name
git config --global user.email

Passo 10: Configura l’accesso SSH a GitHub

Questo è l’unico passo davvero fastidioso. Permette al tuo computer di fare push su GitHub senza password. Genera una chiave (Invio per accettare la posizione predefinita, ~/.ssh/id_ed25519):

ssh-keygen -t ed25519 -C "you@example.com"

Avvia l’agente SSH e aggiungi la chiave:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Mostra la chiave pubblica e copia tutto l’output:

cat ~/.ssh/id_ed25519.pub

Su GitHub: Settings → SSH and GPG keys → New SSH key, dai un titolo, incolla la chiave pubblica e salva. Poi testa:

ssh -T git@github.com

La prima volta, scrivi yes per confermare.

Cosa fa. SSH prova l’identità del tuo computer a GitHub con una coppia di chiavi, così i push vengono autenticati automaticamente e in sicurezza.

Checkpoint. Vedi:

Hi username! You've successfully authenticated, but GitHub does not provide shell access.

Se fallisce. Se vedi Permission denied (publickey), controlla se l’agente ha la tua chiave:

ssh-add -l

Se non compare nessuna identità, aggiungila di nuovo con ssh-add ~/.ssh/id_ed25519 e riprova. Se continua a fallire, copia l’errore esatto in Claude Code e chiedigli di spiegare il problema SSH prima di eseguire qualsiasi comando correttivo, e di non cambiare impostazioni non correlate.

Passo 11: Crea il repository su GitHub

Su GitHub, crea un nuovo repository privato chiamato WEBTest, senza README, senza .gitignore e senza license (vuoto). Crealo, poi copia e salva le URL che mostra:

git@github.com:username/WEBTest.git      # SSH
https://github.com/username/WEBTest.git  # HTTPS

Cosa fa. Partire vuoto evita un commit iniziale inutile dal lato di GitHub e rende pulito il primo push dal tuo progetto locale, senza conflitti da mergiare. Usa solo il branch main per questo test minimo.

Checkpoint. Esiste un repository privato e vuoto WEBTest e ne hai copiato l’URL SSH.

Fase 5 · Il progetto

Passo 12: Crea la cartella locale del progetto

In un terminale, vai dove tieni i progetti, crea la cartella, entra e aprila in VS Code:

cd ~/Documents
mkdir WEBTest
cd WEBTest
code .

Se code . fallisce. Conferma che il comando esiste con code --version. Se non viene riconosciuto, apri VS Code manualmente e usa File → Open Folder per aprire la cartella WEBTest (utenti macOS: vedi la nota su code nel Passo 6).

Passo 13: Apri Claude Code

Apri il terminale integrato in VS Code (View → Terminal) e conferma di essere dentro la cartella del progetto:

pwd

L’output dovrebbe finire con /WEBTest (in PowerShell, pwd funziona ugualmente). Poi avvia l’agente:

claude

Passo 14: Invia il prompt del progetto

Incolla questo prompt in Claude Code, sostituendo username con il tuo vero username GitHub:

Create a minimal Astro website in the current folder.

Requirements:

  1. Use Astro.
  2. Create a simple home page.
  3. Display the visitor’s current local time.
  4. Update the time client-side every second.
  5. Add a clear page title.
  6. Keep the design minimal.
  7. Make the project compatible with Vercel.
  8. Initialize Git.
  9. Use main as the default branch.
  10. Add this GitHub remote: git@github.com:username/WEBTest.git
  11. Run the production build and fix any build errors.
  12. Commit the initial project.
  13. Push the project to main.
  14. Verify that the repository contains the project files.
  15. Report every command executed.
  16. Stop and explain the error if any command fails.
  17. Do not continue past a failed check.

Approvare le azioni. Claude Code può chiedere il permesso prima di eseguire un comando. Leggi prima il comando. Non approvare nulla che non capisci e che modifica file fuori dalla cartella del progetto o cambia la configurazione di sistema. Rivedi i file generati prima di continuare.

Fase 6 · Esegui in locale, builda e fai push

Passo 15: Esegui e builda il sito

Installa le dipendenze se l’agente non l’ha già fatto, poi avvia il server di sviluppo:

npm install
npm run dev

Astro stampa una URL locale, di solito http://localhost:4321. Aprila e verifica che la pagina si carichi, che il titolo sia visibile, e che l’ora appaia e scorra.

Cosa fa. npm run dev avvia un server di sviluppo che ricarica in tempo reale mentre modifichi. Resta in esecuzione e occupa il terminale: premi Ctrl+C per fermarlo.

Ora conferma che builda anche per la produzione (un server di sviluppo che funziona non garantisce un build che funziona):

npm run build

Checkpoint. Il build finisce senza errori. Non fare push finché non ci riesce.

Passo 16: Verifica il remote di Git

git remote -v
git branch --show-current

Checkpoint. Il remote punta al tuo repo WEBTest, e il branch è main.

Passo 17: Fai push del progetto su GitHub

Claude Code potrebbe aver già fatto commit e push nel Passo 14. Questo passo lo verifica e ti dà i comandi per finire a mano se serve:

git status

Se dice nothing to commit, working tree clean, le tue modifiche locali sono committate. Se ci sono file non committati, committali prima:

git add .
git commit -m "Initial Astro website"

In ogni caso, esegui il push per assicurarti che il branch sia su GitHub (un working tree pulito significa committato, non necessariamente pushato):

git push -u origin main

Cosa fa. git push manda i tuoi commit locali su GitHub.

Checkpoint. Apri il repo su GitHub e conferma di vedere package.json, astro.config.mjs, src e public.

Fase 7 · Deploy su Vercel

Passo 18: Importa il repository in Vercel

In Vercel: Add New → Project, trova il repo WEBTest e fai Import. Vercel dovrebbe rilevare Astro da solo. La configurazione attesa è:

Framework Preset: Astro
Build Command:    npm run build
Output Directory: dist
Install Command:  npm install

Cosa fa. Vercel si collega al tuo repo GitHub, lo builda nel cloud e hosta il risultato. Non scrivi tu questi valori, li compila Vercel. Se mostra valori diversi, fermati e confrontali con il tuo progetto prima di deployare. Altrimenti scegli Deploy.

Passo 19: Verifica il deploy su Vercel

Aspetta che il deploy finisca. Vercel ti dà una URL come https://web-test.vercel.app. Aprila e conferma:

Deployment status: Ready
Production URL:     carica
HTTPS:              valido, senza avvisi
Orologio dal vivo:  aggiorna ogni secondo
Finestra privata:   funziona

Se non funziona, sistemalo qui prima di continuare. Non toccare il dominio personalizzato finché questa URL non funziona.

Fase 8 · Dominio personalizzato

Passo 20: Aggiungi il dominio personalizzato in Vercel

Nel progetto Vercel: Settings → Domains → Add Domain. Aggiungi www.example.com e, opzionalmente, la radice example.com.

Cosa fa. example.com e www.example.com sono due hostname diversi. Di solito vuoi che entrambi raggiungano lo stesso sito, con uno che reindirizza all’altro come indirizzo canonico, cioè la versione che scegli come URL pubblica principale. Vercel poi mostra i record DNS esatti che ti servono.

Passo 21: Configura i record DNS in Cloudflare

In Cloudflare, scegli il dominio, apri DNS → Records e crea i record che ha chiesto Vercel. Uno tipico è un CNAME per www:

Type    CNAME
Name    www
Target  cname.vercel-dns.com

Per la radice, Vercel può chiedere un record A o un altro valore. Nelle interfacce DNS, @ di solito rappresenta il dominio radice (example.com). Imposta il proxy su DNS only (la nuvola grigia) durante la validazione iniziale per ridurre le variabili mentre Vercel provisiona HTTPS. Salva.

Importante. I valori DNS in questa guida sono esempi. I valori mostrati nel tuo progetto Vercel sono la fonte di verità. Non inventare valori.

Passo 22: Verifica il dominio personalizzato

Di nuovo nelle impostazioni dei domini di Vercel, aspetta che confermi che la configurazione è valida. Poi apri https://www.example.com e https://example.com e verifica: il sito carica, HTTPS funziona senza avvisi di certificato, viene mostrato il progetto corretto, e radice e www risolvono bene.

Cosa fa. I cambiamenti DNS non sono visibili ovunque in una volta. Resolver diversi si aggiornano in momenti diversi, quindi un dispositivo può vedere la nuova configurazione prima di un altro. Non dare per scontato che sia corretto perché hai aggiunto i record, controllalo nel browser.

Il tuo sito è ora online. Il setup iniziale è completo, questo era l’obiettivo principale. I passi 23 e 24 sono il ciclo di manutenzione: come cambiare il sito in sicurezza e verificare ogni deploy. Continua quando sei pronto.

Fase 9 · Cambiarlo e continuare a verificare

Passo 23: Fai modifiche future

Per cambiare il sito in seguito, apri la cartella WEBTest, esegui claude e dagli un prompt riutilizzabile come questo:

Inspect the current project before editing anything.

Add a contact section to the home page.

After implementing the change:

  1. Run the local checks.
  2. Run the production build.
  3. Fix any detected errors before continuing.
  4. Review the diff.
  5. Commit the change.
  6. Push to main.
  7. Wait for the Vercel deployment.
  8. Verify the production website.
  9. Report the production URL and any detected problems.

Do not consider the task complete only because the push succeeded.

Passo 24: Verifica ogni deploy

Questa è l’abitudine che separa “ho fatto push” da “funziona”.

PUSH ≠ DEPLOY ≠ WORKING WEBSITE

Dopo ogni aggiornamento, conferma la cosa reale:

[ ] La URL di produzione risponde
[ ] L'ultima modifica è visibile
[ ] I link funzionano
[ ] Nessun errore critico in console
[ ] Funziona su desktop
[ ] Funziona su mobile

Non considerare mai un aggiornamento fatto solo perché il codice è arrivato su GitHub. Il sito stesso deve essere verificato.

Cosa è appena successo

Hai collegato un dominio tramite Cloudflare, configurato GitHub con SSH, creato e deployato un sito Astro con Claude Code, messo sul tuo dominio con HTTPS, e imparato il ciclo per cambiarlo in sicurezza. Ecco come si collegano i pezzi:

Due percorsi si incontrano in Vercel: il tuo codice sale dal tuo computer, e il tuo dominio scende dal registrar.

PERCORSO DEL CODICE           PERCORSO DEL DOMINIO

Il tuo computer + Claude Code Registrar (proprietario della registrazione)
      |                             |
      v                             v
   GitHub (conserva il codice) Cloudflare (gestisce il DNS)
      |                             |
      v                             v
        \___________  Vercel  _____/
             (builda e hosta il sito)
                        |
                        v
                  yourdomain.com

L’agente ha fatto il lavoro deterministico e ben documentato: scaffolding, Git, deploy. Tu hai tenuto le parti che servono un umano: gli account, le decisioni, e il controllo che ciò che hai pubblicato funzioni davvero.