104 lines
3.4 KiB
Markdown
104 lines
3.4 KiB
Markdown
# 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`)
|
|
|
|
Install the pinned toolchain with:
|
|
|
|
```bash
|
|
mise install
|
|
```
|
|
|
|
### Development Mode (with live reload)
|
|
|
|
Run the Go server with live reload:
|
|
|
|
```bash
|
|
mise run dev
|
|
```
|
|
|
|
This starts the Go server with `air` live reload on `http://localhost:8080`.
|
|
|
|
### Production Mode
|
|
|
|
Run the Go server:
|
|
|
|
```bash
|
|
mise run server-run
|
|
```
|
|
|
|
The server listens on `http://localhost:8080` by default.
|
|
|
|
### Fresh Server Deployment
|
|
|
|
The Compose deployment keeps its database and attachment store in `./data` and
|
|
its editable Markdown source in `./content`.
|
|
|
|
```bash
|
|
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.
|
|
|
|
### Common commands
|
|
|
|
```bash
|
|
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`.
|
|
- `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.
|
|
|
|
## 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.
|