Skip to main content

Zero to Homelab Docusaurus Deployment Guide

· 2 min read

This document describes the complete process for deploying the Zero to Homelab documentation site using Docusaurus.

Project Overview​

  • Site Name: Zero to Homelab
  • Purpose: Self-hosted infrastructure, homelab, and DevOps tutorials
  • Static Site Generator: Docusaurus 3.x
  • Hosting: VPS (DigitalOcean)
  • CI/CD: GitHub Actions
  • Analytics: Matomo
  • DNS: Namecheap and Cloudflare
  • nginx: SSL Certs

Project Structure​

  • docs/ — Main documentation pages in Markdown
  • blog/ — Blog posts and updates
  • src/pages/index.js — Custom homepage
  • static/ — Images and other static assets
  • docusaurus.config.js — Site configuration
  • sidebars.js — Manual sidebar definition

Deployment Steps​

1. Development Environment​

Install dependencies:

npm install

Run development server:

npm run start

Build production site:

npm run build

Serve locally:

npm run serve

2. Remote Deployment (VPS)​

On VPS:

cd /var/www/zerotohomelab
npm install
npm run build
npx serve build -l 3000

(Optional: use systemd or PM2 to persist serve process)

3. GitHub Integration​

Push repo to GitHub:

git remote add origin https://github.com/yourusername/zerotohomelab.git
git push -u origin main

4. GitHub Actions for Auto Deployment​

Workflow: .github/workflows/deploy.yml

name: Deploy to VPS

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout
      uses: actions/checkout@v3

    - name: Install Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'

    - name: Install dependencies
      run: npm ci

    - name: Build site
      run: npm run build

    - name: Deploy via SCP
      run: scp -r build/* user@your-vps-ip:/var/www/zerotohomelab/
      env:
        SSH_PRIVATE_KEY: ${{ secrets.SSH_KEY }}

Set your SSH key in repo secrets: SSH_KEY

5. Custom Homepage + Featured Articles​

src/pages/index.js includes:

  • Hero section
  • Featured articles using <FeatureCard />
  • CTA to subscribe

6. Analytics (Matomo)​

In docusaurus.config.js:

scripts: [
  {
    src: 'https://analytics.zerotohomelab.dev/matomo.js',
    async: true,
  },
  {
    type: 'text/javascript',
    children: `
      var _paq = window._paq = window._paq || [];
      _paq.push(['trackPageView']);
      _paq.push(['enableLinkTracking']);
      _paq.push(['setTrackerUrl', 'https://analytics.zerotohomelab.dev/matomo.php']);
      _paq.push(['setSiteId', '1']);
    `,
  },
]

Notes​

  • Sidebar is manually defined in sidebars.js
  • Broken link checks are enabled (can be disabled via onBrokenLinks)
  • Static site is production-ready and monitored using Matomo
  • GitHub Actions handle automatic deployment to VPS on push to main