Documentation

How to run, configure, and deploy the almanac frontend and backend.

Frontend

Quick Start

Get almanac-web running locally in under a minute.

git clone https://github.com/wihlarkop/almanac-web
cd almanac-web
cp .env.example .env.local   # set PUBLIC_API_BASE_URL
bun install
bun dev

The dev server starts at http://localhost:4321.

Configuration

Create a .env.local file at the repo root:

# URL of the Almanac API (no trailing slash)
PUBLIC_API_BASE_URL=http://localhost:8080

For production, set this to your deployed API URL (e.g. https://almanac-api.wihlarkop.com).

Deployment

The frontend is deployed to Cloudflare Pages. Production deploys are triggered by pushing a version tag.

# Deploy to production
git tag v1.0.0
git push origin v1.0.0

Pushes to main run CI only — they do not deploy to production.

Backend

Quick Start

The backend is a Rust/Axum API. You need Rust 1.95+ installed.

git clone https://github.com/wihlarkop/almanac
cd almanac
cargo run

The API starts at http://localhost:8080. Swagger UI is available at /swagger-ui.

API Reference

Key endpoints:

Endpoint	Description
GET /api/v1/models	List models with filtering and pagination
GET /api/v1/models/:provider/:id	Get a single model
GET /api/v1/search	Fuzzy search across models
GET /api/v1/providers	List all providers

Full interactive docs: almanac-api.wihlarkop.com/swagger-ui ↗

Deployment

The backend is deployed to Render and auto-deploys on every push to main. A Docker image is also built and pushed to GitHub Container Registry on each deploy.

Note: Render's free tier sleeps after inactivity. The first request after idle takes 10–20 seconds to respond.