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.

From an Empty Folder to a Live Website: A Complete Beginner's Guide

· ai-systems, tooling, web

The one-minute overview

Prefer to watch? Here is the whole manual as one guided video, narrated end to end, with every provider screen animated (captions in English):

The full 24-step course, narrated

Domain, Cloudflare, GitHub, Claude Code and Vercel, from zero to production.

This is a complete, follow-along manual for a first-timer. Every step has the exact command, a Checkpoint telling you what you should see, and, where people commonly get stuck, an If it fails note. An AI agent (Claude Code) does the deterministic work: scaffolding, Git, deploys. You keep the accounts, the decisions and the verification.

Throughout, replace example.com with your real domain and username with your real GitHub username. Do not skip a checkpoint. If a command is not recognized or an output looks wrong, stop and fix it before moving on.

A quick note on terms: a terminal is the text app where you type commands. On macOS open Terminal; on Windows use PowerShell or Windows Terminal; on Linux use your terminal app. Later, VS Code has its own built-in terminal too.

Phase 1 · The domain and DNS

Step 1: Buy a domain

Buy a domain from Hostinger or any registrar, for example example.com. Keep access to the registrar account: you will change its nameservers next.

Checkpoint. You can open the domain management panel at your registrar.

Step 2: Create a Cloudflare account

Create a free Cloudflare account, then: log in, select Add a domain, enter the domain from Step 1, and choose the free plan. Continue until Cloudflare shows two assigned nameservers, similar to:

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

Checkpoint. Cloudflare displays two nameservers assigned to your domain.

Step 3: Connect the domain to Cloudflare

In the registrar’s domain panel, find the nameserver configuration and replace the current nameservers with the two from Cloudflare. Save.

What this does. Nameservers tell the internet which DNS provider is authoritative for your domain. After this change, Cloudflare becomes the place where you manage the domain’s DNS records.

Checkpoint. Back in Cloudflare, the domain status becomes Active. Do not continue until it does (this can take minutes to hours).

Phase 2 · Accounts

Step 4: Create a GitHub account

Create a GitHub account, verify the email, and log in. Note your GitHub username, you will use it repeatedly.

Checkpoint. Email verified, GitHub dashboard accessible, username saved.

Step 5: Create a Vercel account

Create a Vercel account using Log in with GitHub, and authorize Vercel to access the GitHub account from Step 4. Do not create a project yet.

Checkpoint. Your Vercel account is connected to GitHub.

Phase 3 · Local tools

Step 6: Install Visual Studio Code

Download and install Visual Studio Code from its official site (macOS, Windows or Linux). Open it once to confirm it starts, then close it.

If you are on macOS. Enable the code command you will use later: open VS Code, press Cmd+Shift+P, type Shell Command: Install 'code' command in PATH, and run it.

Checkpoint. VS Code opens successfully.

Step 7: Install Git

Install Git (macOS: xcode-select --install or the official installer; Windows: Git for Windows; Linux: your package manager). Then, in a terminal:

git --version

Checkpoint. It prints a version, for example git version 2.50.0. Do not continue if the command is not recognized.

Step 8: Install Claude Code

Install Claude Code following the official instructions for your operating system, then verify:

claude --version

Checkpoint. It prints the installed version. Do not continue until Claude Code starts correctly.

Phase 4 · Git identity and GitHub access

Step 9: Configure your Git identity

Set the name and email Git attaches to your commits. Use the same email as your GitHub account:

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

What this does. Every commit is stamped with this identity. Matching the email to your GitHub account is what links your commits to your profile.

Checkpoint. These print the values you just set:

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

Step 10: Configure GitHub SSH access

This is the one genuinely fiddly step. It lets your computer push to GitHub without passwords. Generate a key (press Enter to accept the default location, ~/.ssh/id_ed25519):

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

Start the SSH agent and add the key:

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

Show the public key and copy the full output:

cat ~/.ssh/id_ed25519.pub

In GitHub: Settings → SSH and GPG keys → New SSH key, give it a title, paste the public key, and save. Then test:

ssh -T git@github.com

The first time, type yes to confirm.

What this does. SSH proves your computer’s identity to GitHub with a key pair, so pushes are authenticated automatically and securely.

Checkpoint. You see:

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

If it fails. If you see Permission denied (publickey), check whether the agent has your key:

ssh-add -l

If no identity is listed, add it again with ssh-add ~/.ssh/id_ed25519 and retry. If it still fails, copy the exact error into Claude Code and ask it to explain the SSH problem before running any corrective command, and not to change unrelated settings.

Step 11: Create the GitHub repository

On GitHub, create a new private repository named WEBTest with no README, no .gitignore, and no license (start empty). Create it, then copy and save the URLs it shows:

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

What this does. Starting empty avoids an unnecessary initial commit on GitHub’s side and makes the first push from your local project clean, with no conflicts to merge. Use only the main branch for this minimal test.

Checkpoint. An empty private WEBTest repository exists and you copied its SSH URL.

Phase 5 · The project

Step 12: Create the local project folder

In a terminal, move to where you keep projects, create the folder, enter it, and open it in VS Code:

cd ~/Documents
mkdir WEBTest
cd WEBTest
code .

If code . fails. Confirm the command exists with code --version. If it is not recognized, open VS Code manually and use File → Open Folder to open the WEBTest folder (macOS users: see the code note in Step 6).

Step 13: Open Claude Code

Open the integrated terminal in VS Code (View → Terminal) and confirm you are inside the project folder:

pwd

The output should end in /WEBTest (in PowerShell, pwd also works). Then start the agent:

claude

Step 14: Send the project prompt

Paste this prompt into Claude Code, replacing username with your real GitHub username:

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.

Approving actions. Claude Code may ask permission before running a command. Read the command first. Do not approve anything you do not understand that modifies files outside the project folder or changes system configuration. Review the generated files before continuing.

Phase 6 · Run locally, build, and push

Step 15: Run and build the website

Install dependencies if the agent has not already, then start the dev server:

npm install
npm run dev

Astro prints a local URL, usually http://localhost:4321. Open it and verify the page loads, the title is visible, and the time is shown and ticking.

What this does. npm run dev runs a development server that live-reloads as you edit. It keeps running and holds the terminal: press Ctrl+C to stop it.

Now confirm it also builds for production (a working dev server does not guarantee a working build):

npm run build

Checkpoint. The build completes with no errors. Do not push until it does.

Step 16: Verify the Git remote

git remote -v
git branch --show-current

Checkpoint. The remote points at your WEBTest repo, and the branch is main.

Step 17: Push the project to GitHub

Claude Code may already have committed and pushed in Step 14. This step verifies that and gives you the commands to finish manually if needed:

git status

If it says nothing to commit, working tree clean, your local changes are committed. If there are uncommitted files, commit them first:

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

Either way, run the push to make sure the branch is on GitHub (a clean working tree means committed, not necessarily pushed):

git push -u origin main

What this does. git push sends your local commits to GitHub.

Checkpoint. Open the repo on GitHub and confirm you can see package.json, astro.config.mjs, src and public.

Phase 7 · Deploy on Vercel

Step 18: Import the repository into Vercel

In Vercel: Add New → Project, find the WEBTest repo, and Import. Vercel should auto-detect Astro. The expected configuration is:

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

What this does. Vercel connects to your GitHub repo, builds it in the cloud, and hosts the result. You do not type these values, Vercel fills them in. If it shows different values, stop and compare them with your project before deploying. Otherwise select Deploy.

Step 19: Verify the Vercel deployment

Wait until the deployment completes. Vercel gives you a URL like https://web-test.vercel.app. Open it and confirm:

Deployment status: Ready
Production URL:     loads
HTTPS:              valid, no warnings
Live clock:         updating every second
Private window:     works

If it does not work, fix it here before continuing. Do not touch the custom domain until this URL works.

Phase 8 · Custom domain

Step 20: Add the custom domain in Vercel

In the Vercel project: Settings → Domains → Add Domain. Add www.example.com and, optionally, the root example.com.

What this does. example.com and www.example.com are two different hostnames. You normally want both to reach the same website, with one redirecting to the other as the canonical address, meaning the version you choose as the primary public URL. Vercel then shows the exact DNS records you need.

Step 21: Configure the DNS records in Cloudflare

In Cloudflare, select the domain, open DNS → Records, and create the records Vercel asked for. A typical one is a CNAME for www:

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

For the root, Vercel may ask for an A record or another value. In DNS interfaces, @ commonly represents the root domain itself (example.com). Set the proxy status to DNS only (the grey cloud) during initial validation to reduce variables while Vercel provisions HTTPS. Save.

Important. The DNS values in this guide are examples. The values shown inside your Vercel project are the source of truth. Do not invent values.

Step 22: Verify the custom domain

Back in Vercel’s domain settings, wait until it confirms the configuration is valid. Then open both https://www.example.com and https://example.com and verify: the site loads, HTTPS works with no certificate warnings, the correct project is shown, and root and www resolve correctly.

What this does. DNS changes are not visible everywhere at once. Different resolvers update at different times, so one device may see the new configuration before another. Do not assume it is correct because the records were added, check it in the browser.

Your website is now live. The initial setup is complete, this was the main goal. Steps 23 and 24 are the maintenance loop: how to change the site safely and verify every deployment. Keep going when you are ready.

Phase 9 · Change it and keep verifying

Step 23: Make future changes

To change the site later, open the WEBTest folder, run claude, and give it a reusable prompt like this:

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.

Step 24: Verify every deployment

This is the habit that separates “I pushed” from “it works”.

PUSH ≠ DEPLOY ≠ WORKING WEBSITE

After every update, confirm the real thing:

[ ] Production URL responds
[ ] Latest change is visible
[ ] Links work
[ ] No critical console errors
[ ] Desktop works
[ ] Mobile works

Never consider an update done just because the code reached GitHub. The website itself has to be verified.

What just happened

You wired a domain through Cloudflare, set up GitHub with SSH, scaffolded and deployed an Astro site with Claude Code, put it on your own domain with HTTPS, and learned the loop for changing it safely. Here is how the pieces connect:

Two paths meet at Vercel: your code travels up from your computer, and your domain travels down from the registrar.

CODE PATH                     DOMAIN PATH

Your computer + Claude Code   Registrar (owns the registration)
      |                             |
      v                             v
   GitHub (stores the code)   Cloudflare (manages DNS)
      |                             |
      v                             v
        \___________  Vercel  _____/
             (builds and hosts the site)
                        |
                        v
                  yourdomain.com

The agent handled the deterministic, well-documented work: scaffolding, Git, deploys. You kept the parts that need a human: the accounts, the decisions, and checking that what shipped really works.