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.
Static sites: why the problem is easy
Section titled “Static sites: why the problem is easy”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.
How Vercel builds and deploys Astro
Section titled “How Vercel builds and deploys Astro”Vercel’s model: connect a Git repository; every push triggers a build and a deployment.
- Trigger: a push (or PR) on a connected GitHub/GitLab/Bitbucket repository fires a webhook.
- Clone and detect: Vercel clones the commit and detects the framework (Astro is auto-detected, preset values below).
- Install: runs the install command, picking the package manager from the lockfile (
pnpm-lock.yaml,package-lock.json,yarn.lock,bun.lock). - Build: runs the build command (
astro build) in an isolated build container with a Node.js version you choose. - Output: collects the output directory (
distfor Astro static output). - Deploy: uploads the files to Vercel’s global CDN as an immutable deployment with its own unique URL (
my-wiki-abc123-team.vercel.app). - 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.
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.
Optional: vercel.json
Section titled “Optional: vercel.json”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/).
Deploying from the CLI
Section titled “Deploying from the CLI”The Git integration is the main path, but the CLI is useful for one-offs and for custom CI:
npm i -g vercelvercel loginvercel link # associate this directory with a projectvercel # create a preview deploymentvercel --prod # deploy to productionvercel env pull .env.local # fetch environment variables for local devvercel 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 integrationname: deployon: 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.
Preview deployments
Section titled “Preview deployments”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
noindexsignals, but do not rely on that to hide sensitive content. - Use ignored build step (Project Settings, or
ignoreCommandinvercel.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
Section titled “Environment variables”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 aPUBLIC_prefix. In recent Astro versions the typedastro:envAPI lets you declare schema and access (client/server, public/secret).
// astro.config.mjs (Astro 5): declare typed env varsimport { 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 }), }, },});vercel env add PUBLIC_ANALYTICS_ID productionvercel env lsvercel env pull .env.local # keep .env* out of GitKeep .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.
Custom domains
Section titled “Custom domains”To serve the site at wiki.example.com (or the apex example.com):
- In Project Settings, Domains, add the domain.
- Add DNS records at your DNS provider as Vercel instructs. Commonly:
- Subdomain (
wiki.example.com): aCNAMEto Vercel’s target (shown in the dashboard). - Apex (
example.com): anArecord to the IP Vercel gives (aCNAMEis not allowed at the apex, see Linux & Networking; some providers supportALIAS/ANAME), or delegate the whole domain’s nameservers to Vercel.
- Subdomain (
- Vercel verifies the DNS and provisions a TLS certificate automatically (Let’s Encrypt-style ACME) and renews it. HTTP is redirected to HTTPS.
- Choose a canonical host (
wwwversus apex) and let the other redirect to it.
Verify the result with the tools you already know:
dig +short wiki.example.comdig wiki.example.com CNAME +shortcurl -sI https://wiki.example.com | head -n 10openssl s_client -connect wiki.example.com:443 -servername wiki.example.com </dev/null 2>/dev/null | openssl x509 -noout -issuer -datesIf 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).
Caching and headers
Section titled “Caching and headers”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
preloadis a long commitment (it tells browsers to force HTTPS for the whole domain, including subdomains, for up to two years); addpreload/includeSubDomainsonly 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 -Iand browser DevTools; confirmx-vercel-cache: HITon repeated requests for cached assets.
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.
Free-tier and practical limits
Section titled “Free-tier and practical limits”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.
Alternatives
Section titled “Alternatives”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: pageson: {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@v4Operating a static site
Section titled “Operating a static site”Even this tiny system benefits from the DevOps habits earlier in the section:
- Quality gates before deploy:
astro check, link checking (e.g.,lycheeoverdist/), 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 keepnpm cias 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).
Key takeaways
Section titled “Key takeaways”- A static Astro site builds to
dist/and needs only a CDN; the whole deployment contract is “install,astro build, servedist”. - 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
digandcurl. - Cache hashed
/_astro/*assets forever and revalidate HTML; set security headers and redirects invercel.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.
Exercises
Section titled “Exercises”- 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.
- Hands-on. Add
vercel.jsonheaders for immutable caching of/_astro/*and security headers; verify withcurl -Ithat they appear, and that HTML is not cached for long. - Hands-on. Attach a custom domain, then use
digandopenssl s_clientto confirm the DNS records and the certificate issuer and expiry. - Conceptual. You rename
/devops/ci-cd/to/devops/pipelines/. List everything that can break and how to prevent each break. - 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.
Further reading
Section titled “Further reading”- Vercel documentation: Projects and Deployments, Environment Variables, Domains, Headers and Redirects (
vercel.jsonreference). - 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.