Deploy

GitHub Setup

Create a repo, push your project, and prepare for deployment.
GitHub Setup info →

Cloudflare Pages

Recommended. Adapter included. Free forever with unlimited bandwidth.
Cloudflare Pages info →

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 →

Firebase Hosting

Google infrastructure. Deploy dist folder via Firebase CLI.
Firebase Hosting 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 →

cPanel / Plesk

Shared hosting with control panel. Upload dist to public_html.
cPanel / Plesk info →

Static & PHP Hosting

Upload dist folder to any static host or PHP shared hosting.
Static & PHP Hosting info →

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

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

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:

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

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

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

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

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

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

Cloudflare Pages

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

Vercel

• Build command: npm run build
• Output directory: dist
• Adapter: vercel()
• Framework preset: Astro

Netlify

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

Firebase Hosting

• Build command: npm run build
• Public directory: dist
• Requires Firebase CLI

AWS (S3 + CloudFront)

• Upload dist/ to an S3 bucket
• Configure CloudFront as CDN
• More steps, more control

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

• Upload dist/ contents to public_html/
• No build step needed on the server
• Works on any shared hosting

---

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

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

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

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

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

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

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.