Verleihnix

Community tool-lending platform. Neighbours share tools, track loans, earn points.

Features

• Tool management — list, search, photo uploads, categories
• Loan lifecycle — request, approve, extend, return, overdue tracking
• Holds & appointments — queue for popular items, schedule handovers
• Points & gamification — earn/spend points for lending activity, configurable point values
• Feedback & ratings — borrower/lender reviews with photos
• Admin panel — SQLAdmin at /admin with CRUD for all models, bulk actions, runtime settings
• Internationalisation — German (de) with Babel, locale switcher
• Email verification — token-based account activation
• Geolocation — address-based search, location privacy controls
• OpenTelemetry — optional tracing integration
• Background tasks — Huey worker for emails and scheduled jobs

Quick Start (Development)

Without Docker

Requires mise (installs Python 3.14 + uv automatically):

mise install
uv sync
cp .env.dev .env          # or use .env.dev directly
uv run alembic upgrade head
uv run verleihnix create-admin --username admin --email admin@local --password admin
uv run verleihnix          # starts the dev server on :8000

With Docker

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

This gives you:

Service	URL
App (hot-reload)	http://localhost:8000
Admin panel	http://localhost:8000/admin
Mailpit (catch-all email UI)	http://localhost:8025

Source is bind-mounted — edits reload instantly.

Production

1. Configure

cp .env.example .env
# Edit .env — at minimum set SECRET_KEY, ADMIN_SECRET_KEY, BASE_URL, SMTP credentials

2. Run

docker compose up -d --build

This starts the app and a Huey worker for background tasks (emails, etc).

3. Migrate & seed admin

docker compose exec app uv run alembic upgrade head
docker compose exec app uv run verleihnix create-admin --username admin

Architecture

docker-compose.yml
├── app       — FastAPI served by uvicorn (:8000)
├── worker    — Huey consumer for background tasks
└── volumes   — uploads/ and data/ (SQLite DB + Huey state)

SQLite is the default database. For multi-worker production deployments, switch DATABASE_URL to PostgreSQL (PostGIS support is auto-detected).

Running Tests

uv sync                  # includes dev dependencies
uv run pytest            # 147 tests

Project Layout

verleihnix/              Application code
├── models/              SQLAlchemy domain models (15 entities)
├── routes/              FastAPI route modules
├── templates/           Jinja2 + HTMX templates
├── translations/        Babel i18n (de)
├── admin.py             SQLAdmin setup
├── admin_auth.py        Admin authentication backend
├── admin_views.py       Admin model views & bulk actions
├── cli.py               CLI commands (create-admin)
├── config.py            Pydantic settings (env-driven)
├── instance_settings.py Runtime configuration service
├── main.py              App factory
├── tasks.py             Huey background tasks
└── tracing.py           OpenTelemetry integration
migrations/              Alembic migrations
tests/                   Pytest suite (147 tests)
spec/                    Design specs & pseudocode

Admin Panel

Available at /admin for users with role=ADMIN. Features:

• CRUD for all models (users, tools, loans, feedback, fines, points, invitations)
• Bulk deactivate users (admin-safe), force-close overdue loans
• Runtime instance settings (invite_only, federation_scope, maintenance_mode)
• Separate session with 1-hour expiry

uv run verleihnix create-admin --username admin

Environment Variables

All settings are prefixed with VERLEIHNIX_. See .env.example for the full list.