🌐 Architecture
- Production: quartz.loca.zone (Static Nginx from
/var/www/quartz-loca/current) - Dev Bench: dev.quartz.loca.zone (Hot-reload, proxies to local
8081) - 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 | Runs Dev Bench on 8081. Nginx proxies WebSocket TLS via port 3002. |
| Deploy Prod | npm run deploy:static | Builds docs/ and symlinks output to /var/www/quartz-loca/current. |
| Bounce Service | systemctl --user restart quartz-tinker | Restarts the background dev daemon. |
⚠️ Node 22 Required. If path issues occur, run:
export PATH="/home/loca/dev/quartz/quartz/node-v22.16.0-linux-x64/bin:$PATH"
🎨 Configuration & Editing
1. Visual Configuration
Use the Interactive Config Builder to generate settings, then paste them directly into quartz.config.yaml.
2. Content Editing
- Dev Bench: Edit Markdown in
content/(auto-reloads). - Production: Edit Markdown in
docs/, then runnpm run deploy:static.
🛠️ Technical Details
- WebSocket Proxying: Node binds WS to local port
3003(--wsPort). Nginx terminates TLS on public port3002(--wsPublicPort) and proxies traffic to prevent Node crashes. - Builder:
content/sandbox/builder.htmlis a standalone, offline-safe HTML/JS file with zero external dependencies. - Deployment Verification: Run
python3 scripts/workflowz/verify-deployment.pyto validate paths, services, and SSL endpoints. - Directory Isolation: Keep
docs/(Prod) andcontent/(Dev) strictly separated. Do not symlink them.