Get started - Raven docs

Raven is the backend for a new publishing platform and powers The Stacks.

API Documentation¶

The API documentation is available at [base url]/api/v1/docs

Deployment¶

The easiest way to deploy Raven is to use the docker-compose setup from deploy/local/. See the deploy README and follow the instructions for the Full deployment.

Workspace Structure¶

This is a pnpm monorepo. Packages are defined in pnpm-workspace.yaml.

Path	Package	Description
`backend-ts/`	`@raven/backend-ts`	TypeScript/Hono HTTP server
`admin-ui/`	`@raven/admin-ui`	Admin web interface
`eslint-config/`	`@raven/eslint-config`	Shared linter configuration
`eslint-rules/`	`@raven/eslint-rules`	Custom lint rules
`cli/`	`@raven/cli`	`raven` command-line interface
`importers/*/`	`@raven/importer-*`	Content importers, one per format
`core/*/`	`@raven/core-*`	Shared tools between packages
`tests/`	`@raven/integration-tests`	Integration tests (Docker-based)
`admin-ui-e2e/`	`@raven/e2e-tests`	Playwright E2E tests for admin-ui
`parity-tests/`	`@raven/parity-tests`	Backend tests (Docker-based)

There are additionally the following folders that are not packages.

Path	Description
`backend/`	Legacy Python/Flask backend. Not used anymore
`deploy`	Configuration and scripts supporting deployment
`docs/`	Documentation site (MyST)

Get started¶

There are two ways to get an environment set up for development.

Use the provided devcontainer
Develop on the metal of your machine

Develop in Devcontainer¶

Follow the instructions in the devcontainer README

Develop on Metal¶

Prerequisites¶

Node.js >= 24
pnpm >= 12
- Using corepack: npm install --global corepack@latest && corepack enable pnpm
Docker
FFmpeg (provides ffprobe, used to inspect uploaded audio and video)
- macOS: brew install ffmpeg
VSCode

Setup¶

pnpm install
deploy/local/docker-compose-dev.sh up  # MySQL and MinIO

cd backend-ts
cp raven.example.toml raven.toml
MIGRATION_DATABASE_URI="mysql://root:root_password@localhost:4306/raven?charset=utf8mb4" pnpm db:migrate
pnpm dev  # API at http://localhost:7001

Common Commands¶

Run commands from the repo root unless otherwise noted.

TypeScript Backend¶

In the backend-ts folder, you can run these commands.

# Migrate the DB
MIGRATION_DATABASE_URI="mysql://root:root_password@localhost:4306/raven?charset=utf8mb4" pnpm db:migrate

# Run the backend
pnpm dev

See backend-ts README.md for more.

Testing¶

# Run all tests across the workspace
pnpm test

# Run backend-ts unit tests only
pnpm --filter @raven/backend-ts test

# Run integration tests (spins up Docker services)
pnpm --filter @raven/integration-tests test

# Run integration tests in watch mode
pnpm --filter @raven/integration-tests test:watch

Linting & Formatting¶

# Lint all packages
pnpm lint

# Lint a specific package
pnpm --filter @raven/backend-ts lint

# Format all files
pnpm format

# Check formatting without writing
pnpm format:check

Type Checking¶

# Type-check all packages
pnpm typecheck

# Type-check a specific package
pnpm --filter @raven/backend-ts typecheck

Documentation¶

pnpm -F @raven/docs live:thestacks  # The Stacks docs at http://localhost:3000
pnpm -F @raven/docs live:raven  # Raven docs at http://localhost:3001
pnpm -F @raven/docs build  # static HTML in docs/*/_build/html

Database (Drizzle ORM)¶

Run these from the backend-ts/ directory or with --filter:

# Generate migrations from schema changes
pnpm --filter @raven/backend-ts db:generate

# Apply migrations
pnpm --filter @raven/backend-ts db:migrate

# Push schema directly (dev only)
pnpm --filter @raven/backend-ts db:push

Contributing¶

Please read our contribution guidelines before submitting pull requests.

License¶

MIT License