scholarr/README.md

scholarr

API-first, self-hosted scholar tracking in the spirit of the *arr ecosystem.

What This Includes

• Multi-user accounts with admin-managed lifecycle
• Cookie session auth with CSRF enforcement
• Scholar CRUD + name-search discovery + profile image management
• Per-user ingestion settings and scheduler
• Manual runs with idempotency behavior
• Run history and continuation queue diagnostics/actions
• Publications workflow (new / all, mark-selected-read, mark-all-read)
• Vue 3 + Vite frontend served from the same container image as the API

Docker Image

• Image: justinzeus/scholarr
• Published by GitHub Actions on every push to main
• Architectures: linux/amd64, linux/arm64
• Tags:
  • latest
  • sha-<short_commit>

Quick Deploy (Copy Compose + Fill Env)

1. Copy docker-compose.yml and .env.example into your deployment directory.
2. Create .env from .env.example.
3. Set at minimum:
   • SESSION_SECRET_KEY
   • POSTGRES_PASSWORD
4. Pull and start:

docker compose pull
docker compose up -d

5. Open:

• App + API: http://localhost:8000
• Health check: http://localhost:8000/healthz

The SPA and API are same-origin by default in this deployment model.

Required Environment Variables

Variable	Required	Purpose
SESSION_SECRET_KEY	Yes	Session signing key. Use a long random value.
POSTGRES_PASSWORD	Yes	Database password for the bundled Postgres service.

Optional startup bootstrap:

Variable	Default	Purpose
BOOTSTRAP_ADMIN_ON_START	0	Auto-create admin on app start.
BOOTSTRAP_ADMIN_EMAIL	empty	Admin email for bootstrap.
BOOTSTRAP_ADMIN_PASSWORD	empty	Admin password for bootstrap.
BOOTSTRAP_ADMIN_FORCE_PASSWORD	0	Force-reset bootstrap admin password if exists.

Ports

Port	Service	Description
8000	app	scholarr API + frontend

Volumes

Volume	Container Path	Purpose
postgres_data	/var/lib/postgresql/data	Postgres persistence
scholar_uploads	/var/lib/scholarr/uploads	Scholar image upload persistence

Upgrade

docker compose pull
docker compose up -d

Development Workflow

Default docker-compose.yml is deployment-oriented (prebuilt image).

For local development with source mounts + Vite dev server:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build

Then open:

• API: http://localhost:8000
• Frontend dev server: http://localhost:5173

Test and Quality Commands

Backend:

docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app uv run pytest tests/unit
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app uv run pytest -m integration

Frontend:

cd frontend
npm install
npm run typecheck
npm run test:run
npm run build

Contract drift check:

python3 scripts/check_frontend_api_contract.py

API Base

• Base path: /api/v1
• Success envelope:
  • {"data": ..., "meta": {"request_id": "..."}}
• Error envelope:
  • {"error": {"code": "...", "message": "...", "details": ...}, "meta": {"request_id": "..."}}

Logging

Important envs:

• LOG_LEVEL
• LOG_FORMAT (console or json)
• LOG_REQUESTS
• LOG_UVICORN_ACCESS
• LOG_REQUEST_SKIP_PATHS
• LOG_REDACT_FIELDS