Quick Start#

Get your library open for business in under two minutes.

1. Launch with Docker Compose#

git clone https://github.com/onlydole/overdue.git
cd overdue
docker compose up --build

That's it. The database is created, demo shelves and volumes are seeded, bot players are active, and the server is running. Open http://localhost:8000.

2. Register a librarian#

Visit http://localhost:8000/register in your browser, pick an avatar, and create your account. You now have a library card.

3. Shelve your first volume#

Navigate to any shelf and click New Volume. Give it a title and some content -- this is knowledge you want to keep fresh.

4. Watch the dust settle#

Head to the Reading Room (http://localhost:8000). Your volume's Dewey Score is already ticking down. The clock is running.

5. Review before it's too late#

Open your volume and hit Review (or press Enter). The score resets to 100, you earn XP, and your streak begins.

6. Check the leaderboard#

Visit /leaderboard to see where you stack up against the bot players. They're already accumulating XP. Can you catch them?

Using the CLI#

Docker Compose commands for managing the library:

# Shuffle the bot leaderboard
docker compose exec overdue overdue bots simulate

# Add more bots to the competition
docker compose exec overdue overdue bots add obsessive --count 2

# Check your stats summary (requires overdue auth login first)
docker compose exec overdue overdue stats summary

# Re-seed demo data
docker compose exec overdue overdue seed seed --reset

Using the API#

If you prefer curl, register and get a library card first:

# Register
curl -X POST http://localhost:8000/api/librarians/register \
  -H "Content-Type: application/json" \
  -d '{"username": "ada", "email": "ada@example.com", "password": "Lovelace1815!"}'

# Login (get your library card)
curl -X POST http://localhost:8000/api/librarians/login \
  -H "Content-Type: application/json" \
  -d '{"username": "ada", "password": "Lovelace1815!"}'

# Check the library's mood
curl http://localhost:8000/api/reading-room/health

Next steps#

• Gameplay Guide -- XP, ranks, badges, streaks, and mood
• Configuration -- Tune decay rates and game balance
• Bot Players -- Manage your AI competition
• API Endpoints -- Full endpoint reference
• Architecture -- How it all fits together