Skip to content

Deploying Static Sites on Vercel

What you’ll learn. How a Git push becomes a live Astro Starlight site on Vercel; what the build and the edge network actually do; how preview deployments, environment variables, and custom domains work; how to control caching and security headers; and how Cloudflare Pages, Netlify, and GitHub Pages compare. This is the short, practical capstone: it applies Git & Workflows, CI/CD, and Linux & Networking (DNS, TLS) to a real, small system.

An Astro site (this wiki is built with Astro and Starlight) compiles Markdown into plain HTML, CSS, and JavaScript files in a dist/ directory. There is no server to run: any web server or CDN that can serve files will do. This is the simplest end of the spectrum in Cloud Fundamentals: no VMs, no containers, no database, no on-call.

Markdown + Astro components --(astro build)--> dist/
index.html
devops/ci-cd/index.html
_astro/*.css, *.js (hashed filenames)
pagefind/ (search index, if enabled)

Static deployment gives you: very low latency (files served from edge locations near users), high availability, nearly zero operational burden, tiny attack surface, and generous free tiers. The cost is that anything dynamic (auth, forms, personalization) needs an API/serverless function or a third-party service.

Vercel’s model: connect a Git repository; every push triggers a build and a deployment.

  1. Trigger: a push (or PR) on a connected GitHub/GitLab/Bitbucket repository fires a webhook.
  2. Clone and detect: Vercel clones the commit and detects the framework (Astro is auto-detected, preset values below).
  3. Install: runs the install command, picking the package manager from the lockfile (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lock).
  4. Build: runs the build command (astro build) in an isolated build container with a Node.js version you choose.
  5. Output: collects the output directory (dist for Astro static output).
  6. Deploy: uploads the files to Vercel’s global CDN as an immutable deployment with its own unique URL (my-wiki-abc123-team.vercel.app).
  7. Promote: for the production branch, the production domain alias is atomically pointed at the new deployment. Because every deployment is immutable and the alias flip is atomic, there is no half-deployed state, and instant rollback is just re-pointing the alias to a previous deployment. This is blue/green deployment (CI/CD) as the platform default.

Default settings for Astro (visible and overridable in Project Settings):

Setting Value
Framework preset Astro
Install command npm install (or inferred from lockfile)
Build command astro build (or npm run build)
Output directory dist
Node.js version Project setting (match your local/.nvmrc/engines)

For a static site no adapter is needed. If you later add server-side rendering (SSR) or API routes, use the @astrojs/vercel adapter, which turns server routes into serverless/edge functions.

astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
export default defineConfig({
site: 'https://wiki.example.com', // used for canonical URLs, sitemap, RSS
integrations: [
starlight({ title: 'Lectures for Myself' }),
],
// output: 'static' is the default: pure files, no adapter required
});

Set site to your final production URL; Astro uses it for canonical links and the sitemap. If you deploy to a subpath, also set base.

Configuration can live in the repo, which is better than clicking in a dashboard because it is reviewable and versioned (IaC spirit).

{
"$schema": "https://openapi.vercel.sh/vercel.json",
"framework": "astro",
"buildCommand": "npm run build",
"outputDirectory": "dist",
"cleanUrls": true,
"trailingSlash": true
}

Starlight emits devops/ci-cd/index.html, so trailingSlash: true matches the generated structure and avoids redirect churn. Check that your internal links use trailing slashes consistently (as in this wiki: /devops/ci-cd/).

The Git integration is the main path, but the CLI is useful for one-offs and for custom CI:

Terminal window
npm i -g vercel
vercel login
vercel link # associate this directory with a project
vercel # create a preview deployment
vercel --prod # deploy to production
vercel env pull .env.local # fetch environment variables for local dev
vercel rollback # re-promote a previous deployment (see docs for options)

In a custom pipeline (for example if you want tests to gate deployment), use the CLI with a scoped token stored as a CI secret (DevSecOps):

# .github/workflows/deploy.yml: alternative to the built-in Git integration
name: deploy
on:
push: {branches: [main]}
permissions: {contents: read}
jobs:
deploy:
runs-on: ubuntu-latest
env:
VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: {node-version: 22, cache: npm}
- run: npm ci
- run: npm run build # fail here before touching Vercel
- run: npx vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
- run: npx vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
- run: npx vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

For a personal wiki the built-in Git integration is almost always enough; add CI only if you want link checking, linting, or tests to gate the deploy.

Every push to a non-production branch and every pull request gets its own immutable preview deployment with a unique URL, and Vercel comments the link on the PR. This is the per-PR ephemeral environment pattern (CI/CD) for free.

Why previews matter even for a solo author:

  • Review a rendering of a large lecture (math, tables, asides) before merging to main.
  • Share a draft URL without publishing it on the production domain.
  • Test configuration changes (headers, redirects, new integrations) safely.

Details worth knowing:

  • Previews use Preview-scoped environment variables, distinct from Production ones.
  • Preview URLs may be protected by Vercel Authentication (login required) depending on project settings; this keeps drafts private. Decide deliberately whether previews of a personal notes site should be public.
  • Branch-specific domains (my-wiki-git-feature-x-team.vercel.app) are stable per branch; the per-deployment URL is unique per commit.
  • Search engines: previews are typically served with noindex signals, but do not rely on that to hide sensitive content.
  • Use ignored build step (Project Settings, or ignoreCommand in vercel.json) to skip builds when nothing relevant changed, saving build minutes in monorepos:
{ "ignoreCommand": "git diff --quiet HEAD^ HEAD -- src/ public/ astro.config.mjs package.json" }

(The command exits 0 to skip the build and non-zero to proceed; here “no differences” skips.)

Environment variables configure a build without committing secrets or per-environment values.

  • Defined per project in the dashboard (or vercel env add NAME production), scoped to Production, Preview, and/or Development.
  • Build-time vs runtime: for a static Astro site everything is resolved at build time and baked into the output. Changing a variable requires a redeploy.
  • Astro exposure rules: variables prefixed with PUBLIC_ are available in client-side code (and therefore visible to every visitor); others are only available at build/server time. Never put secrets behind a PUBLIC_ prefix. In recent Astro versions the typed astro:env API lets you declare schema and access (client/server, public/secret).
// astro.config.mjs (Astro 5): declare typed env vars
import { defineConfig, envField } from 'astro/config';
export default defineConfig({
env: {
schema: {
PUBLIC_ANALYTICS_ID: envField.string({ context: 'client', access: 'public', optional: true }),
SEARCH_API_KEY: envField.string({ context: 'server', access: 'secret', optional: true }),
},
},
});
Terminal window
vercel env add PUBLIC_ANALYTICS_ID production
vercel env ls
vercel env pull .env.local # keep .env* out of Git

Keep .env files in .gitignore. A static wiki usually needs few or no secrets; the best secret is the one you do not have (DevSecOps). Vercel also injects system variables (VERCEL_ENV, VERCEL_URL, VERCEL_GIT_COMMIT_SHA), handy for showing a build version in the footer.

To serve the site at wiki.example.com (or the apex example.com):

  1. In Project Settings, Domains, add the domain.
  2. Add DNS records at your DNS provider as Vercel instructs. Commonly:
    • Subdomain (wiki.example.com): a CNAME to Vercel’s target (shown in the dashboard).
    • Apex (example.com): an A record to the IP Vercel gives (a CNAME is not allowed at the apex, see Linux & Networking; some providers support ALIAS/ANAME), or delegate the whole domain’s nameservers to Vercel.
  3. Vercel verifies the DNS and provisions a TLS certificate automatically (Let’s Encrypt-style ACME) and renews it. HTTP is redirected to HTTPS.
  4. Choose a canonical host (www versus apex) and let the other redirect to it.

Verify the result with the tools you already know:

Terminal window
dig +short wiki.example.com
dig wiki.example.com CNAME +short
curl -sI https://wiki.example.com | head -n 10
openssl s_client -connect wiki.example.com:443 -servername wiki.example.com </dev/null 2>/dev/null | openssl x509 -noout -issuer -dates

If DNS still points elsewhere, the certificate cannot be issued; propagation depends on the previous TTL, which is why you lower TTLs before a migration. A CAA record, if you use one, must permit the CA Vercel uses. The apex-with-nameserver-delegation option gives easiest management, while keeping DNS at your registrar keeps your options open (and email records stay under your control).

Where caching happens: the CDN edge (Vercel’s), the browser, and any intermediate proxies. For static files, Vercel’s defaults are sensible: HTML is revalidated so a new deployment appears immediately, while assets are cached according to their headers. Astro’s build puts JS/CSS in /_astro/ with content-hashed filenames (e.g., index.4f2a9c1b.css), which are safe to cache forever because any change yields a new filename.

The standard strategy:

Content Cache policy Why
HTML pages public, max-age=0, must-revalidate (revalidate each time, cheap with ETags) New deployments visible immediately
/_astro/* hashed assets public, max-age=31536000, immutable Filename changes when content changes
Images/fonts in public/ with stable names Moderate max-age (a day to a week) or hash them Can’t be immutable if the URL stays the same

Configure headers in vercel.json:

{
"headers": [
{
"source": "/_astro/(.*)",
"headers": [
{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
]
},
{
"source": "/(.*)",
"headers": [
{ "key": "X-Content-Type-Options", "value": "nosniff" },
{ "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" },
{ "key": "X-Frame-Options", "value": "DENY" },
{ "key": "Permissions-Policy", "value": "camera=(), microphone=(), geolocation=()" },
{ "key": "Strict-Transport-Security", "value": "max-age=63072000; includeSubDomains; preload" }
]
}
],
"redirects": [
{ "source": "/old-path/", "destination": "/devops/ci-cd/", "permanent": true }
]
}

Notes:

  • HSTS with preload is a long commitment (it tells browsers to force HTTPS for the whole domain, including subdomains, for up to two years); add preload/includeSubDomains only when every subdomain really supports HTTPS.
  • A strict Content-Security-Policy is valuable but tricky with Starlight’s inline scripts and KaTeX; add one in report-only mode first and tighten gradually.
  • Use redirects (permanent 308 or temporary) when you rename a page so existing links and bookmarks keep working. Renaming slugs without redirects breaks every inbound link, including your own cross-links between lectures.
  • Check results with curl -I and browser DevTools; confirm x-vercel-cache: HIT on repeated requests for cached assets.
Terminal window
curl -sI https://wiki.example.com/_astro/some-file.css | grep -iE 'cache-control|x-vercel-cache|etag'

Because deployments are immutable and the alias flips atomically, you do not usually need to purge a cache after deploying; the new deployment is a fresh set of objects. That is a major advantage of immutable deployments over overwriting files on a shared server.

Hobby/free tiers typically limit build minutes, bandwidth, and concurrent builds, and may restrict commercial use; a personal wiki generally fits comfortably. Large sites (thousands of pages with images) can have long builds: keep images optimized (Astro’s <Image>), avoid committing large binaries (Git & Workflows), cache dependencies (done by the platform), and keep the Node version aligned between local and CI. Always read the current plan limits before relying on them.

All of these implement the same idea: Git push, build in a container, deploy immutable output to a CDN.

Platform Notes
Cloudflare Pages (and Workers static assets) Very generous free tier with unlimited bandwidth on the static tier (check current terms), global network, tight integration with Cloudflare DNS/CDN/Workers; configuration via wrangler.toml/dashboard; headers in a _headers file, redirects in _redirects
Netlify The pioneer of this workflow; strong build plugins, forms, split testing; netlify.toml for config, _headers/_redirects files; deploy previews and branch deploys
GitHub Pages Free and simple for public repos; deploys via an Actions workflow (actions/deploy-pages); fewer features (no per-PR previews by default, limited header control)
AWS S3 + CloudFront Maximum control and good for AWS-centric shops; you assemble bucket, OAC, CDN, certificates, invalidations (usually via IaC); more work for the same result
Render, Fly.io, others Static site options plus easy backends
Self-host (Nginx/Caddy on a VPS) Full control; you own TLS renewal, patching, uptime (Linux & Networking)

How to choose for a personal site: take whichever has the lowest friction with your Git host and DNS; the migration cost between them is low because the artifact is just dist/. Avoid proprietary features you cannot easily move (platform-specific build plugins, edge functions) unless they buy you something real. Keep a README note of the build command and output directory; that is the whole contract.

A GitHub Pages workflow, for comparison:

name: pages
on: {push: {branches: [main]}}
permissions: {contents: read, pages: write, id-token: write}
concurrency: {group: pages, cancel-in-progress: true}
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: {node-version: 22, cache: npm}
- run: npm ci && npm run build
- uses: actions/upload-pages-artifact@v3
with: {path: dist}
deploy:
needs: build
runs-on: ubuntu-latest
environment: {name: github-pages}
steps:
- uses: actions/deploy-pages@v4

Even this tiny system benefits from the DevOps habits earlier in the section:

  • Quality gates before deploy: astro check, link checking (e.g., lychee over dist/), and a build in CI on every PR. A broken internal link is a bug; check them mechanically (CI/CD).
  • Rollback: promote a previous deployment instantly if a bad commit ships.
  • Monitoring: a free uptime probe or synthetic check against the production URL; certificate and domain-expiry reminders. Domain and DNS expiry cause real outages (Observability).
  • Reproducibility: commit the lockfile, pin the Node version (engines/.nvmrc), and keep npm ci as the install command.
  • Secrets hygiene: scoped deploy tokens, no secrets in the repo, MFA on the Git host and registrar (DevSecOps).
  • Backups: the Git repository is the source of truth; mirror it (a second remote) and keep your DNS registrar details somewhere safe (Incident & Reliability).
  • A static Astro site builds to dist/ and needs only a CDN; the whole deployment contract is “install, astro build, serve dist”.
  • Vercel builds every push into an immutable deployment, atomically aliases production to it, and makes rollback an instant re-point; PRs get automatic preview deployments.
  • Environment variables are scoped (Production, Preview, Development), resolved at build time for static output, and anything PUBLIC_ ends up in the client bundle.
  • Custom domains need correct DNS (CNAME for subdomains, A/ALIAS for the apex); TLS is provisioned and renewed automatically; verify with dig and curl.
  • Cache hashed /_astro/* assets forever and revalidate HTML; set security headers and redirects in vercel.json, and add redirects when you rename pages.
  • Cloudflare Pages, Netlify, and GitHub Pages offer the same model; keep config portable and avoid unnecessary lock-in.
  1. Hands-on. Deploy a fresh Astro Starlight project to Vercel from a Git repo. Open a PR that changes a page and find the preview URL; confirm that production did not change.
  2. Hands-on. Add vercel.json headers for immutable caching of /_astro/* and security headers; verify with curl -I that they appear, and that HTML is not cached for long.
  3. Hands-on. Attach a custom domain, then use dig and openssl s_client to confirm the DNS records and the certificate issuer and expiry.
  4. Conceptual. You rename /devops/ci-cd/ to /devops/pipelines/. List everything that can break and how to prevent each break.
  5. Design. Write a short CI workflow that builds the site, runs a link checker on dist/, and blocks merging if any internal link is broken.
Solution notes (4)

Breakage: external inbound links and bookmarks, search-engine rankings, internal cross-links in other lectures, sitemap entries, and any hardcoded URLs in README or social posts. Prevention: add a permanent (308/301) redirect from old to new in vercel.json, update internal links, rebuild the sitemap, run a link checker in CI, and set canonical URLs via the site option.

  • Vercel documentation: Projects and Deployments, Environment Variables, Domains, Headers and Redirects (vercel.json reference).
  • Astro documentation: “Deploy your Astro Site” (Vercel, Netlify, Cloudflare, GitHub Pages guides), environment variables, and astro:env.
  • Starlight documentation (configuration, site/base, and customization).
  • Cloudflare Pages and Netlify documentation for _headers, _redirects, and build configuration.
  • Ilya Grigorik, High Performance Browser Networking (2013), and the MDN HTTP caching guide, for cache semantics.