Cairnquire

Cairnquire is a Go-first documentation platform for serving Markdown as secure, fast HTML with room for later sync, collaboration, and offline features.

Current Status

This repository now contains the Milestone 1 foundation scaffold:

• Go application server with chi routing, slog logging, config loading, and graceful shutdown
• SQLite/libsql-oriented data layer with startup migrations
• Markdown rendering pipeline with wiki-link rewriting, tag extraction, and SSR templates
• Content-addressed attachment storage with secure serving
• Go-served HTML templates with embedded CSS and browser scripts
• Docker, Compose, CI, OpenAPI, and local development targets

Quick Start

Prerequisites

• mise
• Docker (optional)
• CGO-capable toolchain for go-libsql
• air for Go live reload (go install github.com/air-verse/air@v1.65.1)
• Xcode command-line tools for the optional macOS sync app and CLI

Install the pinned toolchain with:

mise install

Development Mode (with live reload)

Run the Go server with live reload:

mise run dev

This starts the Go server with air live reload on http://localhost:8080.

Production Mode

Run the Go server:

mise run server-run

The server listens on http://localhost:8080 by default.

macOS Sync and CLI

The menu bar sync app and companion CLI live in apps/macos-sync. For local development, start the server with its local-only auth shortcut:

PORT=9000 CAIRNQUIRE_DEV_MODE=1 mise run server-run

cd apps/macos-sync
swift run cairnquire-cli config \
  --server http://localhost:9000 \
  --token dev \
  --folder "$HOME/Documents/Cairnquire"
swift run cairnquire-cli sync
swift run CairnquireSync

The app automatically uses the dev token for localhost servers. For a deployed server, create an API token from /account/tokens/new and store that token in the app settings. See apps/macos-sync/README.md for upload, sync, and Keychain details.

Fresh Server Deployment

The Compose deployment keeps its database and attachment store in ./data and its editable Markdown source in ./content.

cp .env.example .env
# Edit CAIRNQUIRE_PUBLIC_ORIGIN in .env to match your HTTPS URL.
docker compose up -d --build
curl http://127.0.0.1:8080/health

Open ${CAIRNQUIRE_PUBLIC_ORIGIN}/setup in a browser. The first-run wizard creates the admin account and asks whether visitors may create accounts. The setup endpoint closes after the first admin is created. An admin can change the signup setting later from the account page. Compose also starts Mailpit for local email testing; inspect outgoing messages at http://127.0.0.1:8025.

Common commands

mise run server-test
mise run server-build
mise run docker-build
mise run ci
mise run fmt

Configuration

Configuration can come from:

1. config.json via CAIRNQUIRE_CONFIG
2. Environment variables

Supported variables:

• CAIRNQUIRE_PUBLIC_ORIGIN - Required for deployment. Exact public HTTPS origin used for passkeys and device-flow URLs, for example https://cairnquire.example.com.
• CAIRNQUIRE_SERVER_ADDR - Listen address. Defaults to :8080.
• PORT - Optional shorthand for the listen port, for example PORT=9000.
• CAIRNQUIRE_DATABASE_PATH - Local SQLite/libsql path. Defaults to ../../data/db.sqlite when running from apps/server.
• CAIRNQUIRE_DATABASE_PRIMARY_URL - Optional remote libsql primary URL for an embedded replica.
• CAIRNQUIRE_DATABASE_AUTH_TOKEN - Optional auth token for the remote libsql primary.
• CAIRNQUIRE_CONTENT_SOURCE_DIR - Editable Markdown source directory.
• CAIRNQUIRE_CONTENT_STORE_DIR - Content-addressed attachment store.
• CAIRNQUIRE_EMAIL_SMTP_HOST - SMTP host. Set to an empty string in JSON config to disable delivery.
• CAIRNQUIRE_EMAIL_SMTP_PORT - SMTP port. Defaults to 1025.
• CAIRNQUIRE_EMAIL_FROM - Notification sender address.
• CAIRNQUIRE_LOG_LEVEL - Defaults to INFO.
• CAIRNQUIRE_DEV_MODE - Optional local-only auth shortcut. Do not enable on a deployed server.

Dev Mode

With CAIRNQUIRE_DEV_MODE=1, API requests using Authorization: Bearer dev authenticate as the local development admin. This is intended only for localhost testing.

Noted Gaps

• The docs call for golang-migrate, but the current foundation uses an internal migration runner while go-libsql integration details are validated.
• The sync docs describe JSON messages while the Milestone 1 layout mentions a protobuf package; both are preserved in packages/protocol/ pending a later protocol lock.