kamu-oss - GitLite

KO | EN

gitlite — search

#python #ai #llm #android #rust #macos #nodejs #java #awesome #cli #pytorch #security #mcp #openai

kamu-oss

(★ 81)

You favorite book library

파일 탐색기

최종 버전 다운로드 (.zip)

- - pairwithme.md
- - feature_request.md
- - test.yml
- CODE_OF_CONDUCT.md
- CONTRIBUTING.md
- PULL_REQUEST_TEMPLATE.md
- - favicon.ico
  - logo-dark.svg
  - logo.svg
- - __init__.py
  - send_notification.py
- - __init__.py
- - 0001_initial.py
  - 0002_auto_20170324_1829.py
  - 0003_auto_20170327_1419.py
  - 0004_auto_20170327_1740.py
  - 0005_auto_20170327_2051.py
  - 0006_auto_20170405_2353.py
  - 0007_auto_20170411_1702.py
  - 0008_bookcopy_borrow_date.py
  - 0009_library_waitlist_items.py
  - 0010_bookcopy_missing.py
  - __init__.py
- - isbn.html
- - __init__.py
  - test_forms.py
  - test_google.py
  - test_models.py
  - test_notifications.py
  - test_views.py
- __init__.py
- admin.py
- apps.py
- forms.py
- google.py
- models.py
- urls.py
- views.py
- security-checks.sh
- polyfills.js
- testSetup.js
- - __init__.py
  - common.py
  - cron.py
  - dev.py
  - prod.py
  - test.py
- - base.html
  - navbar.html
- - __init__.py
  - test_feature_toggles.py
- __init__.py
- feature_toggles.py
- middleware.py
- urls.py
- wsgi.py
- AI_CHANGELOG.md
- ARCHITECTURE.md
- ASSETS.md
- DATABASE_SCHEMA.md
- DJANGO_STRUCTURE.md
- DOCKER.md
- FEATURES.md
- FRONTEND.md
- TDD_WORKFLOW.md
- TECH_STACK.md
- USER_STORIES.md
- bookcopy.json
- books.json
- library.json
- .keep
- Book details.png
- Detail of return to choose another library.png
- First page.png
- Kamu shelf.png
- README
- - input.css
- - html5-qrcode.min.js
  - htmx.min.js
  - petite-vue.es.js
- - 0001_initial.py
  - 0002_alter_waitlistitem_add_unique_constraint.py
  - __init__.py
- - new_user_on_waitlist_notification_email.txt
  - waitlist_book_available_email.txt
- - __init__.py
  - test_models.py
  - test_tasks.py
  - test_views.py
- __init__.py
- admin.py
- apps.py
- models.py
- tasks.py
- views.py
.coveragerc
.dockerignore
.gitignore
.hawkeyeignore
.hawkeyerc
.mergify.yml
AGENTS.md
compose.yml
Containerfile
LICENSE
Makefile
manage.py
pyproject.toml
README.md
requirements.lock
setup.cfg
uv.lock

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Test](https://github.com/ayr-ton/kamu-oss/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/ayr-ton/kamu-oss/actions/workflows/test.yml)
# 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

| Layer      | Technology                                         |
|------------|----------------------------------------------------|
| Frontend   | Django templates + HTMX + petite-vue + Tailwind CSS |
| Backend    | Django 5.0 (server-rendered HTML)                   |
| Build      | Tailwind CSS standalone CLI (no JS build step)      |
| Database   | PostgreSQL everywhere                               |
| Containers | Podman + podman-compose                             |
| CI/CD      | GitHub Actions                                      |
| Async      | Synchronous (feature-toggled, off by default)       |

## Requirements

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

## Quick Start (Podman)

Start the development environment:

```bash
make dev
```

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

Run migrations and seed data:

```bash
make migrate
make createsuperuser
make loaddata
```

Visit [http://localhost:8000](http://localhost:8000).

### CSS Development

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

```bash
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):

```bash
python manage.py send_overdue_reminders
```

## Quick Start (Local, No Containers)

Create and activate a Python virtual environment:

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

Install dependencies:

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

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

```bash
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:

```bash
python manage.py runserver
```

## Testing

```bash
# 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:

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

To disable Okta authentication:

```bash
unset OKTA_METADATA_URL OKTA_ENTITY_ID
```

## Environment Variables

| Variable                   | Default                | Description                              |
|---------------------------|------------------------|------------------------------------------|
| `DATABASE_URL`            | (required)             | PostgreSQL connection string             |
| `SECRET_KEY`              | (required in prod)     | Django secret key                        |
| `DEBUG`                   | `false`                | Django debug mode                        |
| `OKTA_METADATA_URL`       | (unset)                | Okta SAML2 metadata URL                  |
| `OKTA_ENTITY_ID`          | (unset)                | Okta entity ID                           |

### Email Notifications

| Variable                   | Default                | Description                              |
|---------------------------|------------------------|------------------------------------------|
| `KAMU_ENABLE_ASYNC_TASKS` | `false`                | Enable email notifications               |
| `DJANGO_EMAIL_BACKEND`    | `smtp.EmailBackend`    | Email backend (use `console.EmailBackend` for testing) |
| `DJANGO_EMAIL_FROM`       | (unset)                | Sender address (e.g. `kamu@yourorg.com`) |
| `DJANGO_EMAIL_HOST`       | (unset)                | SMTP server (e.g. `smtp.sendgrid.net`)   |
| `DJANGO_EMAIL_PORT`       | (unset)                | SMTP port (e.g. `587`)                   |
| `DJANGO_EMAIL_HOST_USER`  | (unset)                | SMTP username                            |
| `DJANGO_EMAIL_HOST_PASSWORD` | (unset)             | SMTP password                            |

## Documentation

| Document                       | Purpose                                   |
|-------------------------------|-------------------------------------------|
| `AGENTS.md`                   | AI agent guide and task tracking           |
| `docs/ARCHITECTURE.md`       | System design and principles               |
| `docs/TECH_STACK.md`         | Technology choices and rationale            |
| `docs/TDD_WORKFLOW.md`       | Test-driven development process            |
| `docs/USER_STORIES.md`       | User stories with acceptance criteria      |
| `docs/FEATURES.md`           | Feature breakdown by migration phase       |
| `docs/DJANGO_STRUCTURE.md`   | Target Django project layout               |
| `docs/FRONTEND.md`           | HTMX + petite-vue frontend architecture    |
| `docs/DATABASE_SCHEMA.md`    | Data model documentation                   |
| `docs/DOCKER.md`             | Podman container strategy                  |
| `docs/ASSETS.md`             | Tailwind CSS and static asset management   |
| `docs/AI_CHANGELOG.md`       | Changelog of all AI-driven changes         |

## License

[MIT](LICENSE)