Quartz 4

09 - Digital Garden & Serverless Notes Portal

4 min read

Digital Garden & Serverless Notes Portal (notes.ganeshr.me)

Overview

An enterprise-grade, serverless personal knowledge base and digital garden deployed globally on Cloudflare Pages. Powered by Quartz 4.0, it provides interactive 2D/3D graph exploration, full-text fuzzy search, backlinks, and dark mode, protected at the edge by Cloudflare Zero Trust with 1-click GitHub Single Sign-On (SSO).

1. Architectural Model: Zero VM Footprint

While our core homelab services (hq, wealth, vault, cockpit) run inside Docker containers on our Oracle Cloud VM, the notes portal is architected to be 100% serverless:

flowchart TD
    subgraph Clients ["Client Devices"]
        Mobile["Android Phone (Obsidian Git)"]
        Laptop["Home Laptop (Obsidian Git)"]
        WorkPC["Work / Borrowed PC (Browser)"]
    end

    subgraph SecurityGate ["Cloudflare Edge (Zero Trust)"]
        CF_Access["Cloudflare Zero Trust Access Gateway"]
        GitHub_SSO["GitHub OAuth Identity Provider"]
    end

    subgraph Hosting ["Cloudflare Pages (Global Edge CDN)"]
        Quartz["Quartz 4.0 (Interactive Digital Garden at notes.ganeshr.me)"]
    end

    subgraph CentralStore ["GitHub Private Repository (gs9339/Obsidian)"]
        Repo["Git Branch: main"]
        GHActions["GitHub Actions CI/CD (.github/workflows/deploy.yml)"]
    end

    Mobile -->|Direct Git Push| Repo
    Laptop -->|Direct Git Push| Repo
    WorkPC -->|HTTPS| CF_Access

    CF_Access <-->|1-Click Verify| GitHub_SSO
    CF_Access -->|Authorized - 30-Day Session| Quartz

    Repo -->|Webhook Trigger| GHActions
    GHActions -->|Automated Quartz Build & Deploy| Hosting

Why This Architecture Was Chosen:

  1. Zero Resource Overhead on VM: Conserves the 1 GB RAM on our Oracle AMD Micro VM for core backend services (Authelia, Vaultwarden, Wealthfolio).
  2. GitHub as the Single Source of Truth: All markdown files, assets, and documentation live in a private GitHub repository (gs9339/Obsidian).
  3. Multi-Device Sync:
    • Desktop & Android: Native Obsidian app with obsidian-git automatically pulls and pushes changes every 5 minutes.
    • Any Browser Anywhere: Visit notes.ganeshr.me for instant search, graph exploration, and reading.
    • Quick Web Edits: Press . on github.com/gs9339/Obsidian (github.dev) when editing from a browser without Obsidian installed.
  4. Zero-Trust Lockdown: Completely blocked from the public internet. Only gs9339@gmail.com can access the portal via 1-click GitHub authentication.

2. Service Endpoints & Routing

Public URLEngine / ComponentAuthenticationPurpose
https://notes.ganeshr.meQuartz 4.0Cloudflare Zero Trust (GitHub SSO)Interactive digital garden, graph view, backlinks & full-text search

3. Component Breakdown

A. The Reader: Quartz 4.0

  • Function: Compiles our Obsidian Markdown files into an interactive static website.
  • Features:
    • Interactive 2D/3D knowledge graph view showing linked notes.
    • Internal wikilink resolution ([[Link]]) with live hover popovers.
    • Full-text fuzzy search (Ctrl + K).
    • Automatic dark/light theme switching with custom typography.
    • Tag navigation and auto-generated folder index pages.

B. Cloudflare Zero Trust Access

  • Application ID: 9e86057c-30ce-4585-ae97-a85b4f879349
  • Domain: notes.ganeshr.me
  • Session Duration: 720 hours (30 days “Remember Me”).
  • Identity Providers:
    • GitHub OAuth: 1-click login matching user gs9339 / gs9339@gmail.com.
    • One-Time PIN: Fallback 6-digit email PIN sent to gs9339@gmail.com.

4. Automated CI/CD Pipeline

Every time notes are pushed to main (from our desktop Obsidian or Android phone), a GitHub Action workflow automatically builds and redeploys the site in ~15 seconds:

  • Workflow File: .github/workflows/deploy.yml
  • Runner: ubuntu-22.04
  • Pipeline Optimizations:
    1. Persistent Cache (actions/cache@v4): Caches the Quartz engine and node_modules so repeat runs skip git clone and npm install.
    2. Fast Native Linking: Direct dynamic linking to prebuilt Linux libraries avoids heavy OS package updates.
    3. Concurrency Control: Cancels superseded runs if multiple quick commits occur within a minute.
    4. Deploy: Uses Cloudflare Wrangler to publish static files to Cloudflare Pages edge network.

GitHub Repository Secrets:

Configured at https://github.com/gs9339/Obsidian/settings/secrets/actions:

  • CLOUDFLARE_API_KEY: Cloudflare Global API Key
  • CLOUDFLARE_EMAIL: gs9339@gmail.com

5. Maintenance & Troubleshooting

Triggering a Manual Local Build & Deploy:

# Rebuild and upload directly from local machine
cd /tmp
git clone -b v4 --depth 1 https://github.com/jackyzha0/quartz.git quartz-v4
cd quartz-v4
npm install --ignore-scripts
npm install @img/sharp-linux-x64
export LD_LIBRARY_PATH="/tmp/quartz-v4/node_modules/@img/sharp-libvips-linux-x64/lib:$LD_LIBRARY_PATH"
npx quartz build -d "/home/gs9339/Documents/Obsidian Vault"
 
source ~/.cloudflare_env
CLOUDFLARE_ACCOUNT_ID="5a4dbadba98615936709e0021baac27c" \
CLOUDFLARE_API_KEY="$CLOUDFLARE_API_KEY" \
CLOUDFLARE_EMAIL="$CLOUDFLARE_EMAIL" \
npx wrangler pages deploy public --project-name=notes --branch=main --commit-dirty=true

Checking Cloudflare Access Status:

source ~/.cloudflare_env
curl -s -H "X-Auth-Email: $CLOUDFLARE_EMAIL" -H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
  "https://api.cloudflare.com/client/v4/accounts/5a4dbadba98615936709e0021baac27c/access/apps" | jq .

Graph View

Backlinks