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.

De una carpeta vacía a un sitio web en vivo: guía completa para principiantes

· ai-systems, tooling, web

El resumen en un minuto

¿Preferís verlo? Acá está todo el manual en un solo video guiado, narrado de punta a punta, con cada pantalla de proveedor animada (subtítulos en inglés):

El curso completo de 24 pasos, narrado

Dominio, Cloudflare, GitHub, Claude Code y Vercel, de cero a producción.

Este es un manual completo para seguir paso a paso, pensado para alguien que arranca de cero. Cada paso tiene el comando exacto, una Comprobación que te dice qué deberías ver y, donde la gente suele trabarse, una nota Si falla. Un agente de IA (Claude Code) hace el trabajo determinista: scaffolding, Git, deploys. Vos te quedás con las cuentas, las decisiones y la verificación.

En todo el manual, reemplazá example.com por tu dominio real y username por tu usuario real de GitHub. No te saltees una comprobación. Si un comando no se reconoce o una salida se ve mal, frená y arreglalo antes de seguir.

Una nota sobre términos: una terminal es la app de texto donde escribís comandos. En macOS abrí Terminal; en Windows usá PowerShell o Windows Terminal; en Linux usá tu app de terminal. Más adelante, VS Code tiene su propia terminal integrada.

Fase 1 · El dominio y el DNS

Paso 1: Comprá un dominio

Comprá un dominio en Hostinger o cualquier registrador, por ejemplo example.com. Mantené el acceso a la cuenta del registrador: vas a cambiar sus nameservers en el próximo paso.

Comprobación. Podés abrir el panel de administración del dominio en tu registrador.

Paso 2: Creá una cuenta de Cloudflare

Creá una cuenta gratis de Cloudflare, después: iniciá sesión, elegí Add a domain, ingresá el dominio del Paso 1 y elegí el plan Free. Continuá hasta que Cloudflare muestre dos nameservers asignados, parecidos a:

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

Comprobación. Cloudflare muestra dos nameservers asignados a tu dominio.

Paso 3: Conectá el dominio a Cloudflare

En el panel del dominio en tu registrador, buscá la configuración de nameservers y reemplazá los actuales por los dos de Cloudflare. Guardá.

Qué hace esto. Los nameservers le dicen a internet qué proveedor de DNS es autoritativo para tu dominio. Después de este cambio, Cloudflare pasa a ser donde administrás los registros DNS del dominio.

Comprobación. De vuelta en Cloudflare, el estado del dominio pasa a Active. No continúes hasta que lo haga (puede tardar minutos u horas).

Fase 2 · Cuentas

Paso 4: Creá una cuenta de GitHub

Creá una cuenta de GitHub, verificá el email e iniciá sesión. Anotá tu username de GitHub, lo vas a usar varias veces.

Comprobación. Email verificado, dashboard de GitHub accesible, username guardado.

Paso 5: Creá una cuenta de Vercel

Creá una cuenta de Vercel con Log in with GitHub, y autorizá a Vercel a acceder a la cuenta de GitHub del Paso 4. No crees el proyecto todavía.

Comprobación. Tu cuenta de Vercel está conectada con GitHub.

Fase 3 · Herramientas locales

Paso 6: Instalá Visual Studio Code

Descargá e instalá Visual Studio Code desde su sitio oficial (macOS, Windows o Linux). Abrilo una vez para confirmar que arranca, y cerralo.

Si estás en macOS. Habilitá el comando code que vas a usar después: abrí VS Code, apretá Cmd+Shift+P, escribí Shell Command: Install 'code' command in PATH y ejecutalo.

Comprobación. VS Code abre correctamente.

Paso 7: Instalá Git

Instalá Git (macOS: xcode-select --install o el instalador oficial; Windows: Git for Windows; Linux: tu gestor de paquetes). Después, en una terminal:

git --version

Comprobación. Imprime una versión, por ejemplo git version 2.50.0. No continúes si el comando no se reconoce.

Paso 8: Instalá Claude Code

Instalá Claude Code siguiendo las instrucciones oficiales para tu sistema operativo, después verificá:

claude --version

Comprobación. Imprime la versión instalada. No continúes hasta que Claude Code arranque bien.

Fase 4 · Identidad de Git y acceso a GitHub

Paso 9: Configurá tu identidad de Git

Configurá el nombre y el email que Git adjunta a tus commits. Usá el mismo email que tu cuenta de GitHub:

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

Qué hace esto. Cada commit lleva esta identidad. Que el email coincida con tu cuenta de GitHub es lo que vincula tus commits con tu perfil.

Comprobación. Estos imprimen los valores que acabás de poner:

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

Paso 10: Configurá el acceso SSH a GitHub

Este es el único paso genuinamente fastidioso. Permite que tu computadora pushee a GitHub sin contraseñas. Generá una llave (Enter para aceptar la ubicación por defecto, ~/.ssh/id_ed25519):

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

Arrancá el agente SSH y agregá la llave:

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

Mostrá la llave pública y copiá toda la salida:

cat ~/.ssh/id_ed25519.pub

En GitHub: Settings → SSH and GPG keys → New SSH key, ponele un título, pegá la llave pública y guardá. Después testeá:

ssh -T git@github.com

La primera vez, escribí yes para confirmar.

Qué hace esto. SSH prueba la identidad de tu computadora ante GitHub con un par de llaves, así los push se autentican automáticamente y de forma segura.

Comprobación. Ves:

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

Si falla. Si ves Permission denied (publickey), revisá si el agente tiene tu llave:

ssh-add -l

Si no aparece ninguna identidad, agregala de nuevo con ssh-add ~/.ssh/id_ed25519 y reintentá. Si sigue fallando, copiá el error exacto en Claude Code y pedile que explique el problema de SSH antes de ejecutar cualquier comando correctivo, y que no cambie configuraciones ajenas.

Paso 11: Creá el repositorio en GitHub

En GitHub, creá un repositorio privado nuevo llamado WEBTest, sin README, sin .gitignore y sin license (vacío). Crealo, después copiá y guardá las URLs que muestra:

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

Qué hace esto. Arrancar vacío evita un commit inicial innecesario del lado de GitHub y hace que el primer push desde tu proyecto local sea limpio, sin conflictos para mergear. Usá solo la rama main para esta prueba mínima.

Comprobación. Existe un repositorio privado y vacío WEBTest y copiaste su URL de SSH.

Fase 5 · El proyecto

Paso 12: Creá la carpeta local del proyecto

En una terminal, andá a donde guardás proyectos, creá la carpeta, entrá y abrila en VS Code:

cd ~/Documents
mkdir WEBTest
cd WEBTest
code .

Si code . falla. Confirmá que el comando existe con code --version. Si no se reconoce, abrí VS Code a mano y usá File → Open Folder para abrir la carpeta WEBTest (en macOS, mirá la nota de code en el Paso 6).

Paso 13: Abrí Claude Code

Abrí la terminal integrada en VS Code (View → Terminal) y confirmá que estás dentro de la carpeta del proyecto:

pwd

La salida debería terminar en /WEBTest (en PowerShell, pwd también funciona). Después arrancá el agente:

claude

Paso 14: Enviá el prompt del proyecto

Pegá este prompt en Claude Code, reemplazando username por tu usuario real de 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.

Aprobar acciones. Claude Code puede pedir permiso antes de correr un comando. Leé el comando primero. No apruebes nada que no entiendas que modifique archivos fuera de la carpeta del proyecto o cambie configuración del sistema. Revisá los archivos generados antes de continuar.

Fase 6 · Correr local, buildear y pushear

Paso 15: Corré y buildeá el sitio

Instalá dependencias si el agente todavía no lo hizo, después arrancá el servidor de desarrollo:

npm install
npm run dev

Astro imprime una URL local, normalmente http://localhost:4321. Abrila y verificá que la página carga, que el título se ve, y que la hora aparece y tickea.

Qué hace esto. npm run dev corre un servidor de desarrollo que recarga en vivo mientras editás. Queda corriendo y ocupa la terminal: apretá Ctrl+C para frenarlo.

Ahora confirmá que también buildea para producción (un servidor de desarrollo que anda no garantiza un build que ande):

npm run build

Comprobación. El build termina sin errores. No pushees hasta que lo haga.

Paso 16: Verificá el remote de Git

git remote -v
git branch --show-current

Comprobación. El remote apunta a tu repo WEBTest, y la rama es main.

Paso 17: Pusheá el proyecto a GitHub

Claude Code puede que ya haya commiteado y pusheado en el Paso 14. Este paso lo verifica y te da los comandos para terminar a mano si hace falta:

git status

Si dice nothing to commit, working tree clean, tus cambios locales están commiteados. Si hay archivos sin commitear, commiteálos primero:

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

En cualquier caso, corré el push para asegurarte de que la rama está en GitHub (un working tree limpio significa commiteado, no necesariamente pusheado):

git push -u origin main

Qué hace esto. git push manda tus commits locales a GitHub.

Comprobación. Abrí el repo en GitHub y confirmá que ves package.json, astro.config.mjs, src y public.

Fase 7 · Deploy en Vercel

Paso 18: Importá el repositorio en Vercel

En Vercel: Add New → Project, buscá el repo WEBTest e Import. Vercel debería detectar Astro solo. La configuración esperada es:

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

Qué hace esto. Vercel se conecta a tu repo de GitHub, lo buildea en la nube y hostea el resultado. No escribís estos valores, los completa Vercel. Si muestra valores distintos, frená y comparalos con tu proyecto antes de desplegar. Si no, elegí Deploy.

Paso 19: Verificá el deploy de Vercel

Esperá a que termine el deploy. Vercel te da una URL como https://web-test.vercel.app. Abrila y confirmá:

Deployment status: Ready
Production URL:     carga
HTTPS:              válido, sin avisos
Reloj en vivo:      actualiza cada segundo
Ventana privada:    funciona

Si no funciona, arreglalo acá antes de continuar. No toques el dominio propio hasta que esta URL funcione.

Fase 8 · Dominio propio

Paso 20: Agregá el dominio propio en Vercel

En el proyecto de Vercel: Settings → Domains → Add Domain. Agregá www.example.com y, opcionalmente, la raíz example.com.

Qué hace esto. example.com y www.example.com son dos hostnames distintos. Normalmente querés que ambos lleguen al mismo sitio, con uno redirigiendo al otro como la dirección canónica, es decir la versión que elegís como URL pública principal. Vercel entonces muestra los registros DNS exactos que necesitás.

Paso 21: Configurá los registros DNS en Cloudflare

En Cloudflare, elegí el dominio, abrí DNS → Records y creá los registros que pidió Vercel. Uno típico es un CNAME para www:

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

Para la raíz, Vercel puede pedir un registro A u otro valor. En las interfaces de DNS, @ suele representar el dominio raíz (example.com). Poné el proxy en DNS only (la nube gris) durante la validación inicial para reducir variables mientras Vercel provisiona HTTPS. Guardá.

Importante. Los valores DNS de esta guía son ejemplos. Los valores que muestra tu proyecto de Vercel son la fuente de verdad. No inventes valores.

Paso 22: Verificá el dominio propio

De vuelta en la configuración de dominios de Vercel, esperá a que confirme que la configuración es válida. Después abrí https://www.example.com y https://example.com y verificá: el sitio carga, HTTPS funciona sin avisos de certificado, se muestra el proyecto correcto, y la raíz y www resuelven bien.

Qué hace esto. Los cambios de DNS no se ven en todos lados a la vez. Distintos resolvers actualizan en momentos distintos, así que un dispositivo puede ver la nueva configuración antes que otro. No asumas que está bien porque agregaste los registros, chequealo en el navegador.

Tu sitio ya está en vivo. El setup inicial está completo, ese era el objetivo principal. Los pasos 23 y 24 son el ciclo de mantenimiento: cómo cambiar el sitio de forma segura y verificar cada deploy. Seguí cuando quieras.

Fase 9 · Cambiarlo y seguir verificando

Paso 23: Hacé cambios a futuro

Para cambiar el sitio después, abrí la carpeta WEBTest, corré claude y dale un prompt reutilizable como este:

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.

Paso 24: Verificá cada deploy

Este es el hábito que separa “pusheé” de “funciona”.

PUSH ≠ DEPLOY ≠ WORKING WEBSITE

Después de cada actualización, confirmá lo real:

[ ] La URL de producción responde
[ ] El último cambio se ve
[ ] Los links funcionan
[ ] Sin errores críticos en consola
[ ] Funciona en desktop
[ ] Funciona en mobile

Nunca des una actualización por hecha solo porque el código llegó a GitHub. El sitio en sí tiene que verificarse.

Qué acaba de pasar

Cableaste un dominio por Cloudflare, configuraste GitHub con SSH, armaste y desplegaste un sitio Astro con Claude Code, lo pusiste en tu propio dominio con HTTPS, y aprendiste el ciclo para cambiarlo de forma segura. Así se conectan las piezas:

Dos rutas se encuentran en Vercel: tu código sube desde tu computadora, y tu dominio baja desde el registrador.

RUTA DEL CÓDIGO               RUTA DEL DOMINIO

Tu computadora + Claude Code  Registrador (dueño del registro)
      |                             |
      v                             v
   GitHub (guarda el código)  Cloudflare (administra el DNS)
      |                             |
      v                             v
        \___________  Vercel  _____/
             (buildea y hostea el sitio)
                        |
                        v
                  yourdomain.com

El agente hizo el trabajo determinista y bien documentado: scaffolding, Git, deploys. Vos te quedaste con lo que necesita un humano: las cuentas, las decisiones, y chequear que lo que publicaste realmente funciona.