jeffemmett
/
canvas-website
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
canvas-website/QUARTZ_SYNC_SETUP.md

7.5 KiB
Raw Blame History

Quartz Database Setup Guide

This guide explains how to set up a Quartz database with read/write permissions for your canvas website. Based on the Quartz static site generator architecture, there are several approaches available.

Overview

Quartz is a static site generator that transforms Markdown content into websites. To enable read/write functionality, we've implemented multiple sync approaches that work with Quartz's architecture.

Setup Options

1. GitHub Integration (Recommended)

This is the most natural approach since Quartz is designed to work with GitHub repositories.`

Prerequisites

  • A GitHub repository containing your Quartz site
  • A GitHub Personal Access Token with repository write permissions

Setup Steps

  1. Create a GitHub Personal Access Token:

    • Go to GitHub Settings → Developer settings → Personal access tokens
    • Generate a new token with repo permissions for the Jeff-Emmett/quartz repository
    • Copy the token

  2. Configure Environment Variables: Create a .env.local file in your project root with:

    # GitHub Integration for Jeff-Emmett/quartz
NEXT_PUBLIC_GITHUB_TOKEN=your_github_token_here
NEXT_PUBLIC_QUARTZ_REPO=Jeff-Emmett/quartz

    Important: Replace your_github_token_here with your actual GitHub Personal Access Token.

  3. Set up GitHub Actions (Optional):

    • The included .github/workflows/quartz-sync.yml will automatically rebuild your Quartz site when content changes
    • Make sure your repository has GitHub Pages enabled

How It Works

  • When you sync a note, it creates/updates a Markdown file in your GitHub repository
  • The file is placed in the content/ directory with proper frontmatter
  • GitHub Actions automatically rebuilds and deploys your Quartz site
  • Your changes appear on your live Quartz site within minutes

2. Cloudflare Integration

Uses your existing Cloudflare infrastructure for persistent storage.

Prerequisites

  • Cloudflare account with R2 and Durable Objects enabled
  • API token with appropriate permissions

Setup Steps

  1. Create Cloudflare API Token:

    • Go to Cloudflare Dashboard → My Profile → API Tokens
    • Create a token with Cloudflare R2:Edit and Durable Objects:Edit permissions
    • Note your Account ID

  2. Configure Environment Variables:

    # Add to your .env.local file
NEXT_PUBLIC_CLOUDFLARE_API_KEY=your_api_key_here
NEXT_PUBLIC_CLOUDFLARE_ACCOUNT_ID=your_account_id_here
NEXT_PUBLIC_CLOUDFLARE_R2_BUCKET=your-bucket-name

  3. Deploy the API Endpoint:

    • The src/pages/api/quartz/sync.ts endpoint handles Cloudflare storage
    • Deploy this to your Cloudflare Workers or Vercel

How It Works

  • Notes are stored in Cloudflare R2 for persistence
  • Durable Objects handle real-time sync across devices
  • The API endpoint manages note storage and retrieval
  • Changes are immediately available to all connected clients

3. Direct Quartz API

If your Quartz site exposes an API for content updates.

Setup Steps

  1. Configure Environment Variables:

    # Add to your .env.local file
NEXT_PUBLIC_QUARTZ_API_URL=https://your-quartz-site.com/api
NEXT_PUBLIC_QUARTZ_API_KEY=your_api_key_here

  2. Implement API Endpoints:

    • Your Quartz site needs to expose /api/notes endpoints
    • See the example implementation in the sync code

4. Webhook Integration

Send updates to a webhook that processes and syncs to Quartz.

Setup Steps

  1. Configure Environment Variables:

    # Add to your .env.local file
NEXT_PUBLIC_QUARTZ_WEBHOOK_URL=https://your-webhook-endpoint.com/quartz-sync
NEXT_PUBLIC_QUARTZ_WEBHOOK_SECRET=your_webhook_secret_here

  2. Set up Webhook Handler:

    • Create an endpoint that receives note updates
    • Process the updates and sync to your Quartz site
    • Implement proper authentication using the webhook secret

Configuration

Environment Variables

Create a .env.local file with the following variables:

# GitHub Integration
NEXT_PUBLIC_GITHUB_TOKEN=your_github_token
NEXT_PUBLIC_QUARTZ_REPO=username/repo-name

# Cloudflare Integration
NEXT_PUBLIC_CLOUDFLARE_API_KEY=your_api_key
NEXT_PUBLIC_CLOUDFLARE_ACCOUNT_ID=your_account_id
NEXT_PUBLIC_CLOUDFLARE_R2_BUCKET=your-bucket-name

# Quartz API Integration
NEXT_PUBLIC_QUARTZ_API_URL=https://your-site.com/api
NEXT_PUBLIC_QUARTZ_API_KEY=your_api_key

# Webhook Integration
NEXT_PUBLIC_QUARTZ_WEBHOOK_URL=https://your-webhook.com/sync
NEXT_PUBLIC_QUARTZ_WEBHOOK_SECRET=your_secret

Runtime Configuration

You can also configure sync settings at runtime:

import { saveQuartzSyncSettings } from '@/config/quartzSync'

// Enable/disable specific sync methods
saveQuartzSyncSettings({
  github: { enabled: true },
  cloudflare: { enabled: false },
  webhook: { enabled: true }
})

Usage

Basic Sync

The sync functionality is automatically integrated into your ObsNote shapes. When you edit a note and click "Sync Updates", it will:

  1. Try the configured sync methods in order of preference
  2. Fall back to local storage if all methods fail
  3. Provide feedback on the sync status

Advanced Sync

For more control, you can use the QuartzSync class directly:

import { QuartzSync, createQuartzNoteFromShape } from '@/lib/quartzSync'

const sync = new QuartzSync({
  githubToken: 'your_token',
  githubRepo: 'username/repo'
})

const note = createQuartzNoteFromShape(shape)
await sync.smartSync(note)

Troubleshooting

Common Issues

  1. "No vault configured for sync"

    • Make sure you've selected a vault in the Obsidian Vault Browser
    • Check that the vault path is properly saved in your session

  2. GitHub API errors

    • Verify your GitHub token has the correct permissions
    • Check that the repository name is correct (username/repo-name format)

  3. Cloudflare sync failures

    • Ensure your API key has the necessary permissions
    • Verify the account ID and bucket name are correct

  4. Environment variables not loading

    • Make sure your .env.local file is in the project root
    • Restart your development server after adding new variables

Debug Mode

Enable debug logging by opening the browser console. The sync process provides detailed logs for troubleshooting.

Security Considerations

  1. API Keys: Never commit API keys to version control
  2. GitHub Tokens: Use fine-grained tokens with minimal required permissions
  3. Webhook Secrets: Always use strong, unique secrets for webhook authentication
  4. CORS: Configure CORS properly for API endpoints

Best Practices

  1. Start with GitHub Integration: It's the most reliable and well-supported approach
  2. Use Fallbacks: Always have local storage as a fallback option
  3. Monitor Sync Status: Check the console logs for sync success/failure
  4. Test Thoroughly: Verify sync works with different types of content
  5. Backup Important Data: Don't rely solely on sync for critical content

Support

For issues or questions:

  1. Check the console logs for detailed error messages
  2. Verify your environment variables are set correctly
  3. Test with a simple note first
  4. Check the GitHub repository for updates and issues

References