Skip to content

dev.md

Latest commit

 

History

History
179 lines (127 loc) · 3.51 KB

dev.md

File metadata and controls

179 lines (127 loc) · 3.51 KB

Development Guide

This document covers how to set up and develop Ratatoskr locally.

Prerequisites

  • Bun v1.0 or later
  • An OIDC provider (e.g., Authentik) for authentication testing

Setup

  1. Clone the repository:

    git clone <repository-url>
cd ratatoskr

  2. Install dependencies:

    bun install

  3. Create a .env file (see Configuration below)

  4. Run database migrations:

    bun run db:migrate

  5. Start the development server:

    bun run dev

Configuration

Create a .env file in the project root:

# Server
PORT=4151
HOST=0.0.0.0
BASE_URL=http://localhost:4151

# OIDC - Uses PKCE (public client, no secret needed)
OIDC_ISSUER=https://auth.tionis.dev
OIDC_CLIENT_ID=juhMlePBJWwnVCxbnO5bFJJcaMIN0tVahhfqVj2Q
OIDC_REDIRECT_URI=http://localhost:4151/api/v1/auth/callback

# Storage
DATA_DIR=./data

# Optional: Comma-separated additional browser origins for CORS
# (BASE_URL origin is always allowed)
# CORS_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000

# Optional: Override default quotas
# DEFAULT_MAX_DOCUMENTS=10000
# DEFAULT_MAX_DOCUMENT_SIZE=10485760
# DEFAULT_MAX_TOTAL_STORAGE=1073741824

Available Scripts

Command Description
bun run dev Start dev server with hot reload
bun run start Start production server
bun test Run tests
bun test --watch Run tests in watch mode
bun run lint Check linting and formatting
bun run lint:fix Auto-fix linting and formatting issues
bun run typecheck Run TypeScript type checking
bun run db:migrate Run database migrations

Project Structure

src/
├── index.ts          # Entry point
├── config.ts         # Environment configuration
├── server.ts         # Fastify server setup
├── auth/             # Authentication (OIDC, tokens)
├── api/              # REST API routes
├── sync/             # WebSocket sync handler
├── storage/          # Metadata DB + blob file storage
└── lib/              # Shared utilities (ACL, rate limiting, etc.)

Testing

Tests use Bun's built-in test runner:

# Run all tests
bun test

# Run specific test file
bun test test/acl.test.ts

# Run in watch mode
bun test --watch

Code Style

This project uses Biome for linting and formatting:

# Check for issues
bun run lint

# Auto-fix issues
bun run lint:fix

# Format only
bun run format

Database

SQLite is used for metadata and sync storage:

  • {DATA_DIR}/ratatoskr.db for metadata
  • {DATA_DIR}/automerge.db for Automerge document state

Migrations

Migrations run automatically on startup. To run them manually:

bun run db:migrate

Schema

See DESIGN.md for the full database schema.

API Testing

Health Check

curl http://localhost:4151/health

Create API Token (after authentication)

curl -X POST http://localhost:4151/api/v1/auth/api-tokens \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "dev-token"}'

List Documents

curl http://localhost:4151/api/v1/documents \
  -H "Authorization: Bearer <token>"

Debugging

Enable Debug Logging

Set the DEBUG environment variable:

DEBUG=* bun run dev

Database Inspection

The SQLite database can be inspected with any SQLite client:

sqlite3 ./data/ratatoskr.db