Deploy

This guide walks you through pushing PaperHouse to GitHub and deploying it to the four most popular static hosts.

By the end, your site will be live on the internet with automatic deploys every time you push a change.

Step 1 — Create a GitHub account

Skip this step if you already have one.

Go to github.com/signup
Enter your email, create a password, and pick a username
Verify your email address

GitHub is free for public and private repositories with unlimited collaborators .

Step 2 — Create a GitHub repository

Log in to GitHub
Click the + icon in the top right → New repository
Name it something like paperhouse or my-portfolio
Leave it Public (or Private if you prefer)
Do not check “Add a README file” or “.gitignore” — you already have those
Click Create repository

GitHub will show you a page with setup commands. Copy the repository URL — it looks like:

https://github.com/YOUR_USERNAME/paperhouse.git

Step 3 — Push your local code to GitHub

Open your terminal in the PaperHouse project folder.

Initialize Git (first time only)

git init

Add all files

git add .

Create your first commit

git commit -m "Initial commit"

Connect to GitHub

git remote add origin https://github.com/YOUR_USERNAME/paperhouse.git

Replace YOUR_USERNAME with your actual GitHub username.

Push

git branch -M main
git push -u origin main

If GitHub asks for authentication, use a personal access token — not your password. Create one at github.com/settings/tokens with repo scope .

Refresh your GitHub repository page. Your PaperHouse files should be there.

Step 4 — Choose your host

You can deploy to any of these. All have free tiers.

Host	Best for	Build command	Output
Cloudflare Pages	Fastest global CDN	`npm run build`	`dist`
Netlify	Easiest setup	`npm run build`	`dist`
Vercel	Best DX	`npm run build`	`dist`
GitHub Pages	Free, tied to GitHub	`npm run build`	`dist`

Step 5a — Deploy to Cloudflare Pages

Go to dash.cloudflare.com and log in
Go to Workers & Pages
Click Create application → Pages tab
Click Connect to Git
Select your GitHub repository
Configure the build:
- Production branch: main
- Build command: npm run build
- Build output directory: dist
Click Save and Deploy

Cloudflare builds and deploys your site. Every push to main triggers a new build .

Your site is live at https://your-project.pages.dev.

Custom domain

In Cloudflare Pages → your project → Custom domains
Click Set up a custom domain
Enter your domain and follow DNS instructions

Step 5b — Deploy to Netlify

Go to netlify.com and log in
Click Add new site → Import an existing project
Connect GitHub and select your repository
Netlify auto-detects Astro. Confirm:
- Build command: npm run build
- Publish directory: dist
Click Deploy site

Every push to your main branch redeploys automatically .

Your site is live at https://random-name.netlify.app. Rename it in Site settings → Site information.

Step 5c — Deploy to Vercel

Go to vercel.com and log in
Click Add New → Project
Import your GitHub repository
Vercel auto-detects Astro. Confirm the settings
Click Deploy

Vercel creates a production deployment and a preview deployment for every pull request .

Your site is live at https://your-project.vercel.app.

Step 5d — Deploy to GitHub Pages

GitHub Pages serves your site from the repository itself. You need a small config change first.

Set the base path

Open astro.config.mjs and add:

export default defineConfig({
  site: 'https://YOUR_USERNAME.github.io',
  base: '/paperhouse',
  // ...
});

Replace YOUR_USERNAME and paperhouse with your actual values.

Add a GitHub Actions workflow

Create .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: 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

Enable Pages

Go to your repository → Settings → Pages
Under Source, select GitHub Actions
Push the workflow file

Your site is live at https://YOUR_USERNAME.github.io/paperhouse .

Step 6 — Verify your deployment

After deploying to any host:

Open your live URL
Check the home page loads
Navigate to /works, /blog, /contact, /docs
Open DevTools → Console — check for errors
View source (Ctrl + U) — confirm meta tags are present

Step 7 — Set up a custom domain

Every host above supports custom domains. The general steps:

Buy a domain from Namecheap, Cloudflare, or Google Domains
In your host’s dashboard, add the domain
Update DNS records at your registrar:
- A record → your host’s IP (if provided)
- CNAME record → www → your host’s subdomain
Wait for DNS propagation (1-48 hours)
Enable HTTPS — most hosts do this automatically

Automatic deploys

Once connected, every host above watches your main branch. Push a change and the site rebuilds:

git add .
git commit -m "Update hero copy"
git push

Your site updates in 1-2 minutes.

Environment variables

If you add secrets (API keys, tokens), set them in your host’s dashboard — never commit them to Git.

Cloudflare: Workers & Pages → Settings → Environment variables
Netlify: Site settings → Environment variables
Vercel: Project settings → Environment Variables
GitHub Pages: Repository → Settings → Secrets and variables → Actions

Astro reads them via import.meta.env. Private variables need no prefix. Public ones need PUBLIC_ .

Troubleshooting

“Build failed: Cannot find module.”
Run npm install locally and commit package-lock.json.

“404 on subpages.”
Your base path is wrong. Check astro.config.mjs.

“Styles missing.”
Ensure src/styles/globals.css is imported in src/layouts/Base.astro.

“Site shows old content.”
Hard refresh with Ctrl + Shift + R or clear your CDN cache in the host dashboard.