# Project pack: Komga @ 023ec90

Facts about **Komga** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Komga is a self-hosted server for your digital comics and books. It scans your folders, organises series with covers and metadata, tracks reading per user, and lets you read in the browser or through apps over OPDS and the Komga API. It is light, stable and runs on small machines.

## Version and source
- Repository: https://github.com/gotson/komga
- Pinned commit: `023ec905c10a35bbb8e29095420d266cd3adad60`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/gotson/komga/archive/023ec905c10a35bbb8e29095420d266cd3adad60.zip
- Official docs: https://komga.org/
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/gotson/komga bespoke-komga
  cd bespoke-komga
  git checkout --detach 023ec905c10a35bbb8e29095420d266cd3adad60
  # Prepare development requirements and local configuration first.
  ./gradlew bootRun
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --name komga -p 25600:25600 -v komga-config:/config -v /path/to/your/comics:/data gotson/komga
  # then open http://localhost:25600 and create the first user
  ```

- Needs: Docker for a trial, JDK 21 and Node for development
- Develop: `./gradlew bootRun`
- Test: `./gradlew test`
- Stack: kotlin, typescript (Spring Boot, Vue, Gradle). Difficulty for a non-developer with an AI: **advanced**. A Kotlin Spring Boot server with two web front ends. Libraries, users and metadata need no code; code changes mean Kotlin, Gradle and Vue.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`.

## Customisation points (settings → extend → code)
- **libraries-and-users** [settings]: Folders, scanning and who can read what. → `Server settings → Libraries and Users`
- **metadata** [settings]: Titles, authors and reading direction. → `Series and book pages, ComicInfo.xml files`
- **opds** [extend]: Read from phone or e-reader apps. → `Server settings → OPDS and API docs`
- **web-ui** [code]: Screens and styles. → `next-ui/ and komga-webui/`
- **server** [code]: New API features and scanners. → `komga/src`

## Must keep working
- Database migrations in komga/src. Add new ones; never edit old ones.
- Per-user access and age restriction checks.
- The scanner, which must never modify your files.

## Staying updatable
Use libraries, metadata and OPDS first. Keep code changes in new Kotlin classes or Vue components.

## Data, costs and safety
- Personal data: **yes**. Stored in: A SQLite database in /config; your files remain in your folders. Back up the config folder. Your library files are read, not changed.
- Setting `TZ`: Your time zone so schedules run at the right time.
- Use strong passwords and HTTPS before opening it to the internet.
- Respect copyright. Use it for books you own.

---

# Customising Komga

Komga is a Kotlin server plus web front ends. The documentation covers a lot of configuration.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Server code | komga/src/main/kotlin |
| Database migrations | komga/src/flyway/ |
| Current web UI | komga-webui/src/ |
| Next web UI | next-ui/src/ |
| Desktop tray app | komga-tray/ |
| Docker files | komga/docker/ |

## Use the gentlest change first

1. **Settings (no code):** libraries, users, metadata and OPDS.
2. **Extend:** the API and OPDS.
3. **Code:** Kotlin services and Vue screens.

## Recipes

- **New API endpoint:** add a controller method in the REST controllers and cover it with a test.
- **New metadata field:** add a Flyway migration, extend the domain model and DTOs, then show it in the web UI.

## Running and checking your changes

- `./gradlew test` and run the server on a small sample library.
- Check the web reader and OPDS feed.

## Pitfalls

- The two web UIs are separate. Check which one you are changing.
- Use a copy of your library while developing.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/komga/023ec90/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/komga/023ec90/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/komga/023ec90/r2/SKILL.md)