Solanasis Docs

docs-web-viewer-guide

5 min read

Solanasis Docs Web Viewer — Setup & Usage Guide

Last Updated: 2026-03-28 Status: Active — local Docker deployment via Cloudflare Tunnel

Architecture Overview

┌─────────────────┐               ┌──────────────────┐   CF Tunnel   ┌───────────────────┐
│  Obsidian /      │  file edits   │  Quartz Docker    │ ──────────> │  docs.solanasis.com │
│  SilverBullet    │ ────────────> │  (localhost:3003)  │             │  (Cloudflare Access)│
└─────────────────┘               └──────────────────┘             └───────────────────┘
                                      │ volume mount
                                      v
                                  /home/zasage/_my/
                                  _solanasis/solanasis-docs/

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

Two subdomains, two tools:

  • docs.solanasis.com — Beautiful read-only viewer (Quartz, local Docker via Cloudflare Tunnel)
  • 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: Start Quartz Docs Server

cd /home/zasage/_my/_solanasis/solanasis-scripts
 
# Build and start Quartz docs server
docker compose -f docker-compose.quartz.yml up -d --build
 
# Verify it's running
docker compose -f docker-compose.quartz.yml ps
 
# Check logs (first build takes ~3 minutes for 500+ files)
docker compose -f docker-compose.quartz.yml logs -f
 
# Test locally
curl -s http://localhost:3003 | head -5

Rebuild after Quartz config changes:

docker compose -f docker-compose.quartz.yml up -d --build

Content changes (edits to solanasis-docs/) are picked up automatically by Quartz’s --serve mode.

Note: The Cloudflare Pages project (solanasis-docs) and GitHub Actions workflow are preserved as fallback. To rollback: python3 switch_docs_to_tunnel.py --rollback

Phase 4: Start SilverBullet

cd /home/zasage/_my/_solanasis/solanasis-scripts
 
# Get password from Infisical
export SB_PASSWORD=$(secret get SB_PASSWORD -f shared --plain)
 
# 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. Quartz auto-detects file changes and rebuilds (~5-10 seconds)
  6. Changes appear on docs.solanasis.com immediately after rebuild

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

Quartz docs not accessible

  1. Check container: docker compose -f docker-compose.quartz.yml ps
  2. Check logs: docker compose -f docker-compose.quartz.yml logs --tail 50
  3. Test locally: curl -s http://localhost:3003 | head -5
  4. Rebuild: docker compose -f docker-compose.quartz.yml up -d --build
  5. Check Cloudflare Tunnel: sudo systemctl status cloudflared

Site not updating after edit

  1. Check Quartz logs for rebuild: docker compose -f docker-compose.quartz.yml logs --tail 10
  2. Quartz --serve mode should auto-detect changes; if not, restart: docker compose -f docker-compose.quartz.yml restart

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 container logs: docker compose -f docker-compose.quartz.yml logs
  2. Common issue: malformed frontmatter in an .md file
  3. Rebuild: docker compose -f docker-compose.quartz.yml up -d --build

Costs

ComponentCost
QuartzFree (MIT license)
SilverBulletFree (MIT license)
Docker (local)Free (runs on existing WSL host)
Cloudflare AccessFree tier (50 users)
Cloudflare TunnelFree
Total$0/month

Graph View