🚀 Quartz Cheatsheet
Everything you need to run, configure, and maintain your epic quartz.loca.zone setup.
🌐 Architecture
- Production Site: quartz.loca.zone (Static Nginx, served from
/var/www/quartz-loca/current) - Tinker Bench (Dev): dev.quartz.loca.zone (Live hot-reload, proxies to local
8081) - Visual Config Builder: dev.quartz.loca.zone/sandbox/builder (WYSIWYG config generator)
- q5vault: q5vault.quartz.loca.zone (Standalone vault, proxies to local
8083)
💻 Commands
Root Directory: cd /home/loca/dev/quartz/quartz
| Goal | Command | Description |
|---|---|---|
| Test Changes | npm run serve:dev | Spins up the live Dev Bench on 8081. Nginx handles the wss:// TLS proxy via wsPublicPort: 3002. |
| Deploy Prod | npm run deploy:static | Builds docs/ and symlinks the timestamped release to /var/www/quartz-loca/current. |
| Bounce Service | systemctl --user restart quartz-tinker | Restarts the background dev daemon if it ever hangs. |
⚠️ Node 22 Required. It’s persisted in
~/.bashrcand~/.profile. If path issues occur in a weird shell, run:
export PATH="/home/loca/dev/quartz/quartz/node-v22.16.0-linux-x64/bin:$PATH"
🎨 Configuration & Editing
1. Visual Configuration (No YAML required!)
Use the Interactive Config Builder to visually toggle widgets, swap colors, and pick fonts. Hit “Copy to Clipboard” and paste it over quartz.config.yaml.
2. Content Editing
- Dev Bench: Edit Markdown in
content/(auto-reloads magically). - Production: Edit Markdown in
docs/, then runnpm run deploy:static.
🛠️ Deep Lore & Best Practices
- The Port Split: Node binds the WebSocket server to local port
3003(--wsPort). Nginx terminates TLS on public port3002(--wsPublicPort) and proxies the traffic. This prevents Node from crashing while letting the browser connect securely overwss://. - Zero-Dependency Builder: The WYSIWYG config builder (
content/sandbox/builder.html) is 100% standalone. No npm dependencies, no CDNs. Offline-safe forever. - Verification: Run
python3 scripts/workflowz/verify-deployment.pyto run E2E checks on paths, services, and HTTPS endpoints. - Directory Isolation: Keep
docs/(Prod) andcontent/(Dev) strictly separated. Never symlink them.