Skip to content
Astro Docus

Deploy

Vercel

Import repo, framework Astro, static build. 100 GB bandwidth free.
Vercel info →

Netlify

Connect GitHub repo. Build with npm run build. Drag-and-drop supported.
Netlify info →

Surge

Simple CLI deploy. Push dist to Surge with one command.
Surge info →

AWS

S3 for storage, CloudFront for global CDN. Enterprise-grade.
AWS info →

VPS

Full control with Nginx and Let's Encrypt SSL on your own server.
VPS info →

What Is Deployment?

Section titled “What Is Deployment?”

Deployment is the process of taking your Astro Docus project from your local machine and making it available on the internet. Astro Docus builds to static HTML, CSS, and JavaScript — which means it can be hosted anywhere that serves files.

No server runtime is required. No database. No backend. Just files.

This makes Astro Docus compatible with nearly every hosting provider in existence, from free platforms like Cloudflare Pages and Netlify, to traditional VPS and shared hosting with cPanel.

The Build Command

Section titled “The Build Command”

Before deploying anywhere, you need to build the production version of your site.

Terminal window
npm run build

This command:

  1. Reads all your content (docs, blog, JSON data)
  2. Processes images and assets
  3. Generates static HTML files
  4. Outputs everything to the dist/ folder

The dist/ folder is what gets deployed. Nothing else.

To preview the build locally before deploying:

Terminal window
npm run preview

This runs a local server serving the contents of dist/, exactly as it will appear in production.

Deployment Options at a Glance

Section titled “Deployment Options at a Glance”

Astro Docus can be deployed to any of the following. Each has its own strengths.

# Platform Best For Cost Setup Difficulty
1 Static Hosting Simple sites, quick uploads Free–cheap Easy
2 GitHub Version control + source backup Free Easy
3 Cloudflare Pages Fast global CDN, Git integration Free Easy
4 Vercel Frontend-focused, Git integration Free tier Easy
5 Netlify Drag-and-drop + Git integration Free tier Easy
6 Firebase Hosting Google ecosystem, fast CDN Free tier Medium
7 AWS Enterprise, full control Pay-as-you-go Hard
8 VPS Full control, custom setups Varies Hard
9 cPanel / Plesk Traditional shared hosting Cheap Easy

Each will be covered in detail in its own page.

Choosing the Right Option

Section titled “Choosing the Right Option”

If you are unsure, here is a simple decision path:

  • I just want it online quickly, for free. → Cloudflare Pages or Netlify
  • I want the best performance with zero cost. → Cloudflare Pages
  • I want Git-based deploys with preview environments. → Vercel or Netlify
  • I am already using Google Cloud. → Firebase Hosting
  • I need to deploy to a client’s existing hosting. → cPanel / Plesk
  • I want full control over the server. → VPS
  • I need enterprise infrastructure. → AWS

For most users, Cloudflare Pages is the recommended starting point. It is free, extremely fast, and integrates directly with GitHub.

Prerequisites for Deployment

Section titled “Prerequisites for Deployment”

Before deploying, make sure you have:

  1. A working local build — npm run build completes without errors.

  2. The correct site URL — set in astro.config.mjs:

    site: 'https://yourdomain.com',

    This is used for sitemaps, canonical URLs, and RSS.

  3. The correct adapter — depending on host:

    • Cloudflare: cloudflare({ imageService: 'passthrough' })
    • Vercel: vercel()
    • Netlify: netlify()
    • Static hosts (GitHub Pages, Firebase, cPanel, VPS): remove the adapter block

  4. A Git repository (recommended) — most platforms deploy from GitHub. Setting up Git first makes everything smoother.

  5. A domain name (optional) — every platform provides a free subdomain, but a custom domain looks more professional.

Understanding the Deployment Flow

Section titled “Understanding the Deployment Flow”

Most modern deployment platforms follow the same pattern:

Local project  →  Git push  →  Platform detects change  →  Build  →  Deploy

You commit your code, push it to GitHub, and the platform automatically:

  1. Detects the new commit
  2. Runs npm install and npm run build
  3. Takes the contents of dist/
  4. Publishes them to the CDN

Every future push to the main branch triggers a new deploy. Some platforms also create preview URLs for pull requests, so you can see changes before merging.

For platforms without Git integration (cPanel, some VPS setups), you upload the dist/ folder manually via FTP, SSH, or a control panel file manager.

What You Need to Know Per Platform

Section titled “What You Need to Know Per Platform”

Each platform has its own small quirks. Here is a quick preview of what is covered in the individual guides.

Cloudflare Pages

Section titled “Cloudflare Pages”
  • Build command: npm run build
  • Output directory: dist
  • Adapter: cloudflare({ imageService: 'passthrough' })
  • Free tier includes unlimited bandwidth

Vercel

Section titled “Vercel”
  • Build command: npm run build
  • Output directory: dist
  • Adapter: vercel()
  • Framework preset: Astro

Netlify

Section titled “Netlify”
  • Build command: npm run build
  • Publish directory: dist
  • Adapter: netlify()
  • Drag-and-drop deploy supported

Firebase Hosting

Section titled “Firebase Hosting”
  • Build command: npm run build
  • Public directory: dist
  • Requires Firebase CLI

AWS (S3 + CloudFront)

Section titled “AWS (S3 + CloudFront)”
  • Upload dist/ to an S3 bucket
  • Configure CloudFront as CDN
  • More steps, more control

VPS (Nginx / Apache)

Section titled “VPS (Nginx / Apache)”
  • Upload dist/ via SSH or SFTP
  • Configure Nginx or Apache to serve the folder
  • Point domain to the server IP

cPanel / Plesk

Section titled “cPanel / Plesk”
  • Upload dist/ contents to public_html/
  • No build step needed on the server
  • Works on any shared hosting
Section titled “Setting Up GitHub First (Recommended)”

Even if your chosen platform supports direct upload, using GitHub is recommended because:

  1. You get version history. Every change is tracked.
  2. Platforms deploy automatically when you push.
  3. Preview deploys for pull requests.
  4. Rollback is one click on most platforms.
  5. You can switch platforms later without re-uploading files.

The GitHub setup guide is the second page in this list and covers:

  • Creating a GitHub account
  • Installing Git locally
  • Initializing a repository
  • Pushing your first commit
  • Connecting to a hosting platform

If you are new to Git, start there.

Environment Variables

Section titled “Environment Variables”

Some platforms require environment variables — for example, if your project uses a CMS with API keys. Astro Docus works without any environment variables for the default setup.

If you do need them:

  • Cloudflare Pages — Settings → Environment variables
  • Vercel — Project Settings → Environment Variables
  • Netlify — Site settings → Environment variables
  • Firebase — Functions config or .env file
  • VPS / cPanel — set in the shell or in a .env file

Only set the variables you actually use. Do not expose secrets in client-side code.

Custom Domains

Section titled “Custom Domains”

Every platform offers a free subdomain:

  • Cloudflare: your-project.pages.dev
  • Vercel: your-project.vercel.app
  • Netlify: your-project.netlify.app
  • Firebase: your-project.web.app

To use your own domain:

  1. Add the domain in the platform dashboard.
  2. Update DNS records at your domain registrar.
  3. Wait for propagation (usually minutes, sometimes hours).

Each platform guide covers the DNS setup in detail.

Common Deployment Problems

Section titled “Common Deployment Problems”
Problem Likely Cause Fix
Build fails on the platform Node version mismatch Set Node version in platform settings
Broken images after deploy Wrong site URL Update astro.config.mjs
Pages return 404 Wrong output directory Set output to dist
Slow first load No CDN caching Enable platform caching
Sitemap URLs wrong site URL missing Set it in astro.config.mjs
Adapter mismatch Wrong import Match adapter to platform

Deployment Order — Recommended Path

Section titled “Deployment Order — Recommended Path”

If you are deploying Astro Docus for the first time, follow this order:

  1. Set up Git and GitHub — create a repo, push your code.
  2. Deploy to Cloudflare Pages — free, fast, and integrates with GitHub.
  3. Add a custom domain — if you have one.
  4. Explore other platforms — only if you need them.

This path gets you online in under 15 minutes.

What Comes Next

Section titled “What Comes Next”

This page is the introduction. Each deployment method is covered in its own detailed guide under docs/deploy-hosting/. The planned pages are:

Page File Covers
Static Hosting docs/deploy-hosting/static.md Generic static hosts, manual uploads
GitHub Setup docs/deploy-hosting/github.md Account, Git install, repo, first push
Cloudflare Pages docs/deploy-hosting/cloudflare.md Signup, GitHub connect, direct upload, domain
Vercel docs/deploy-hosting/vercel.md Signup, GitHub connect, direct upload, domain
Netlify docs/deploy-hosting/netlify.md Signup, GitHub connect, drag-drop, domain
Firebase Hosting docs/deploy-hosting/firebase.md Firebase CLI, init, deploy, domain
AWS docs/deploy-hosting/aws.md S3, CloudFront, Route 53
VPS docs/deploy-hosting/vps.md Nginx, SSL, manual deploy
cPanel / Plesk docs/deploy-hosting/cpanel.md File manager, FTP upload, subdomain setup

Each page is self-contained and includes registration steps, connection steps, and troubleshooting.

Quick Recap

Section titled “Quick Recap”
Deployment flow:
  Local project → Git push → Platform build → Live site


Requirements:
  ├── Working local build (npm run build)
  ├── Correct site URL in astro.config.mjs
  ├── Correct adapter for your host
  ├── GitHub account (recommended)
  └── Domain (optional)


Options:
  ├── Static hosting     → manual upload
  ├── GitHub             → source control
  ├── Cloudflare Pages   → free, fast, recommended
  ├── Vercel             → frontend-focused
  ├── Netlify            → drag-and-drop or Git
  ├── Firebase           → Google ecosystem
  ├── AWS                → enterprise
  ├── VPS                → full control
  └── cPanel / Plesk     → shared hosting


Recommended start:
  1. Set up GitHub
  2. Deploy to Cloudflare Pages
  3. Add custom domain

Deployment is not a single step — it is a small workflow. Once Git and one platform are set up, every future change publishes with a single git push.