🚀 The Loca.zone Ultra-Cheat Sheet
Everything you need to run, configure, and maintain your epic quartz.loca.zone setup. 100% idiot-proof.
🌐 The 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 gen)
- q5vault: q5vault.quartz.loca.zone (Standalone vault, proxies to local 8083)
💻 The Holy Trinity of Commands
Run all commands from the repository root:
cd /home/loca/dev/quartz/quartz
| Goal | Command | What it does |
|---|---|---|
| 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. |
⚠️ Prerequisite: Node 22 is required. It’s persisted in
~/.bashrcand~/.profile. If commands fail in a weird shell, run:export PATH="/home/loca/dev/quartz/quartz/node-v22.16.0-linux-x64/bin:$PATH"
🎨 Modifying the Site
1. Visual Configuration (No YAML required!)
Head to 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. Creating Content
- For the Dev Bench: Edit markdown files in
content/. Browser auto-reloads magically. - For Production: Edit markdown files 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. - Docs & Content Separation:
docs/is explicitly isolated fromcontent/. Never symlink them. Prod is Prod. Dev is Dev.