Solanasis Docs

docs-web-viewer-guide

5 min read

Solanasis Docs Web Viewer — Setup & Usage Guide

Last Updated: 2026-03-24 Status: Setup guide — follow phases in order

Architecture Overview

┌─────────────────┐     git push     ┌──────────────────┐     build      ┌──────────────────┐
│  Obsidian /      │ ──────────────> │  GitHub Actions   │ ────────────> │  Cloudflare Pages │
│  SilverBullet    │                 │  (Quartz build)   │               │  docs.solanasis.com│
└─────────────────┘                 └──────────────────┘               └──────────────────┘

┌─────────────────┐   Cloudflare    ┌──────────────────┐
│  SilverBullet    │ <── Tunnel ──> │  edit.solanasis.com│
│  (Docker:3000)   │               │  (Cloudflare Access)│
└─────────────────┘               └──────────────────┘

Two subdomains, two tools:

  • docs.solanasis.com — Beautiful read-only viewer (Quartz static site on Cloudflare Pages)
  • edit.solanasis.com — Editor with auto-save (SilverBullet via Cloudflare Tunnel)

Both protected by Cloudflare Access (email OTP authentication).

Phase 1: Create GitHub Repo for the Site

  1. Go to github.com/dzinreach and create a new private repo: solanasis-docs-site
  2. Push the local site repo: 
    cd C:/_my/_solanasis/solanasis-docs-site
git add -A
git commit -m "Initial Quartz setup for Solanasis docs"
git remote add origin https://github.com/dzinreach/solanasis-docs-site.git
git push -u origin main

Phase 2: Configure GitHub Secrets

You need secrets in both repos:

In solanasis-docs-site repo (Settings > Secrets and variables > Actions):

SecretValueHow to get it
DOCS_REPO_TOKENGitHub PAT with repo scopegithub.com > Settings > Developer settings > Personal access tokens > Fine-grained tokens > create one with read access to solanasis-docs
CLOUDFLARE_API_TOKENCloudflare API tokenCloudflare dashboard > My Profile > API Tokens > Create Token > “Edit Cloudflare Workers” template (needs Pages read/write)
CLOUDFLARE_ACCOUNT_IDYour Cloudflare account IDCloudflare dashboard > any domain > right sidebar “Account ID”

In solanasis-docs repo (Settings > Secrets and variables > Actions):

SecretValueHow to get it
SITE_REPO_TOKENGitHub PAT with repo scopeSame token as above works, or create a separate one with write access to solanasis-docs-site

Phase 3: Create Cloudflare Pages Project

  1. Go to Cloudflare dashboard > Workers & Pages > Create > Pages
  2. Connect to Git > select dzinreach/solanasis-docs-site
    • OR skip git connection — the GitHub Action deploys via Wrangler instead
  3. If using Wrangler deploy (recommended):
    • Just create the project: npx wrangler pages project create solanasis-docs
    • Or let the first GitHub Action run create it automatically

Set Custom Domain

  1. Workers & Pages > solanasis-docs project > Custom domains
  2. Add docs.solanasis.com
  3. Cloudflare auto-configures the DNS CNAME

Phase 4: Start SilverBullet

cd C:/_my/_solanasis/solanasis-scripts
 
# Set your password (change this!)
export SB_PASSWORD="your-secure-password-here"
 
# Start SilverBullet
docker compose -f docker-compose.silverbullet.yml up -d
 
# Verify it's running
docker compose -f docker-compose.silverbullet.yml ps
 
# Check logs
docker compose -f docker-compose.silverbullet.yml logs -f

Test locally: Visit http://localhost:3000 — you should see your vault files.

Add to Cloudflare Tunnel

  1. Cloudflare Zero Trust dashboard > Networks > Tunnels
  2. Select your existing tunnel (or create one)
  3. Public Hostname > Add:
    • Subdomain: edit
    • Domain: solanasis.com
    • Service: http://localhost:3000
  4. Save

Phase 5: Configure Cloudflare Access (Auth)

For docs.solanasis.com

  1. Zero Trust > Access > Applications > Add Application > Self-hosted
  2. Application name: Solanasis Docs (Read)
  3. Subdomain: docs, Domain: solanasis.com
  4. Session duration: 7 days
  5. Add policy:
    • Name: Allow Solanasis Team
    • Action: Allow
    • Include > Emails: dmitri@solanasis.com (add contractor emails as needed)
  6. Identity providers: check “One-time PIN”

For edit.solanasis.com

  1. Repeat the above but:
    • Application name: Solanasis Docs (Edit)
    • Subdomain: edit
    • Consider restricting to just Dmitri’s email (more restrictive than read access)

Test Auth

  1. Open an incognito window
  2. Visit docs.solanasis.com
  3. You should see Cloudflare’s login page
  4. Enter your email, check for the OTP email, enter the code
  5. You should now see the Quartz site

Phase 6: Start the Auto-Push Watcher

# Install dependency
pip install watchdog
 
# Run the watcher (keeps running in foreground)
python C:/_my/_solanasis/solanasis-scripts/docs-auto-push.py
 
# Or with custom settings
python docs-auto-push.py --repo-path C:/_my/_solanasis/solanasis-docs --debounce 60

Run as Background Service (Optional)

To keep it running after closing the terminal, create a Windows Task Scheduler task:

  • Program: python
  • Arguments: C:/_my/_solanasis/solanasis-scripts/docs-auto-push.py
  • Trigger: At system startup
  • Run whether user is logged on or not

Daily Usage

Viewing Docs

  1. Go to docs.solanasis.com
  2. Authenticate with email OTP (once per 7 days)
  3. Browse with sidebar explorer, search, graph view
  4. Everything renders beautifully — wikilinks, callouts, tables, code blocks

Editing Docs

  1. Go to edit.solanasis.com
  2. Authenticate with email OTP
  3. Navigate to the file you want to edit
  4. Edit — changes auto-save immediately to disk
  5. The auto-push watcher commits and pushes within 30 seconds
  6. Quartz rebuilds — changes appear on docs.solanasis.com within ~2-3 minutes

Quick Edit from Reader

  • When viewing a doc on docs.solanasis.com, click the link in the footer to jump to edit.solanasis.com

Excluding Files from Publishing

Entire folders (.quartzignore in quartz.config.ts)

Already excluded:

  • solanasis-client-files/
  • *credential*
  • *secret*
  • .env*
  • .obsidian/
  • _to_organize_categorize/

Individual files (frontmatter)

Add to any .md file’s frontmatter:

---
publish: false
---

This file will be visible in SilverBullet but NOT on docs.solanasis.com.

Troubleshooting

Site not updating after edit

  1. Check if auto-push watcher is running: look for the Python process
  2. Check git status: cd solanasis-docs && git status
  3. Check GitHub Actions: github.com/dzinreach/solanasis-docs-site/actions
  4. Manual push: cd solanasis-docs && git add -A && git commit -m "manual update" && git push

SilverBullet not accessible

  1. Check container: docker compose -f docker-compose.silverbullet.yml ps
  2. Check logs: docker compose -f docker-compose.silverbullet.yml logs
  3. Restart: docker compose -f docker-compose.silverbullet.yml restart
  4. Check Cloudflare Tunnel is running and routing edit.solanasis.com

Cloudflare Access blocking you

  1. Check your email is in the Access policy
  2. Check the OTP email didn’t go to spam (sender: noreply@notify.cloudflare.com)
  3. Try incognito window to clear cached auth cookies

Quartz build failing

  1. Check GitHub Actions logs for errors
  2. Common issue: malformed frontmatter in an .md file
  3. Test locally: cd solanasis-docs-site && npx quartz build

Costs

ComponentCost
QuartzFree (MIT license)
SilverBulletFree (MIT license)
Cloudflare PagesFree tier (500 builds/month)
Cloudflare AccessFree tier (50 users)
Cloudflare TunnelFree
GitHub ActionsFree tier (2,000 min/month)
Total$0/month

Graph View