Kamu

"Some books leave us free and some books make us free." — Ralph Waldo Emerson

Kamu is an application for managing a physical library where you can add books, borrow and return them. Users browse libraries (different offices, cities, or friend groups), borrow available books, and join waitlists for unavailable ones.

Tech Stack

Requirements

• Python 3.12+
• Podman and podman-compose
• Tailwind CSS standalone CLI (for CSS development)

Quick Start (Podman)

Start the development environment:

make dev

This starts the Django app and PostgreSQL via podman-compose.

Run migrations and seed data:

make migrate
make createsuperuser
make loaddata

Visit http://localhost:8000.

CSS Development

When working on templates, run the Tailwind watcher in a separate terminal:

make tailwind-watch

Email Notifications (Optional)

To enable email notifications (waitlist alerts, overdue reminders), set KAMU_ENABLE_ASYNC_TASKS=True in your .env file and configure the DJANGO_EMAIL_* environment variables. Notifications are sent synchronously during the request — no Redis or background workers needed.

For overdue reminders, run the management command on a schedule (e.g. via Cloud Scheduler + Cloud Run Jobs):

python manage.py send_overdue_reminders

Quick Start (Local, No Containers)

Create and activate a Python virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Install dependencies:

uv pip compile pyproject.toml -o requirements.lock
uv pip sync requirements.lock

Set up the database (requires a local PostgreSQL instance):

export DATABASE_URL=postgres://kamu:kamu@localhost:5432/kamu
python manage.py migrate
python manage.py createsuperuser
python manage.py loaddata dump_data/*.json

Start the development server:

python manage.py runserver

Testing

# Via containers
make test

# Locally
make local-test

# With coverage
coverage run manage.py test
coverage report

Authentication

Default (Django Login)

Uses Django's built-in session authentication. Create a superuser with make createsuperuser and log in at /accounts/login/.

Okta SAML2

Set the following environment variables:

OKTA_METADATA_URL='url-of-okta-saml'
OKTA_ENTITY_ID='url-of-okta-login'

To disable Okta authentication:

unset OKTA_METADATA_URL OKTA_ENTITY_ID

Environment Variables

Email Notifications

Documentation

License

MIT