{"id":41650669,"url":"https://github.com/aha-hyeong/kumiho","last_synced_at":"2026-05-07T06:04:51.093Z","repository":{"id":332341731,"uuid":"1133394882","full_name":"aha-hyeong/kumiho","owner":"aha-hyeong","description":"kumiho is self-hosting web media server.","archived":false,"fork":false,"pushed_at":"2026-03-26T14:49:43.000Z","size":88509,"stargazers_count":69,"open_issues_count":18,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T15:42:47.706Z","etag":null,"topics":["comics","docker","ebook","epub","library","manga","novel","pdf","self-hosted","txt","webtoon"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aha-hyeong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-13T09:37:10.000Z","updated_at":"2026-03-26T15:31:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"fc7881e2-85a3-4904-8b73-183c71cee7d0","html_url":"https://github.com/aha-hyeong/kumiho","commit_stats":null,"previous_names":["aha-hyeong/kumiho"],"tags_count":95,"template":false,"template_full_name":null,"purl":"pkg:github/aha-hyeong/kumiho","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aha-hyeong%2Fkumiho","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aha-hyeong%2Fkumiho/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aha-hyeong%2Fkumiho/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aha-hyeong%2Fkumiho/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aha-hyeong","download_url":"https://codeload.github.com/aha-hyeong/kumiho/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aha-hyeong%2Fkumiho/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292631,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["comics","docker","ebook","epub","library","manga","novel","pdf","self-hosted","txt","webtoon"],"created_at":"2026-01-24T16:03:49.918Z","updated_at":"2026-05-07T06:04:51.073Z","avatar_url":"https://github.com/aha-hyeong.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003cimg src=\"web/public/Logo.svg\" alt=\"Logo\" width=\"50\" height=\"50\" style=\"vertical-align: middle;\"/\u003e Kumiho\n\n\u003cdiv align=\"center\"\u003e\n\n[![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=flat-square\u0026logo=discord\u0026logoColor=white)](https://discord.gg/KYaWSCUNQt)\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/aha-hyeong/kumiho?style=flat-square\u0026label=version)\n![Docker Image Size (latest by date)](https://img.shields.io/docker/image-size/ahahyeong/kumiho?style=flat-square)\n![GitHub](https://img.shields.io/github/license/aha-hyeong/kumiho?style=flat-square)\n![Go Version](https://img.shields.io/badge/Go-1.24+-00ADD8?style=flat-square\u0026logo=go)\n![React](https://img.shields.io/badge/React-Vite-61DAFB?style=flat-square\u0026logo=react)\n\n**Ultra-lightweight, High-performance, Self-hosted Web Media Server**\n\n![Login Page](docs/images/login-page.png)\n\n\u003c/div\u003e\n\n---\n\n🌐 **Language**: English | [日本語](README.ja.md) | [한국어](README.ko.md)\n\n---\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e **v0.15.0 Library Rescan Notice**: The recursive leaf-series scanner changes how nested folders are interpreted. After updating, a library rescan is required, and existing reading progress or metadata links are not guaranteed to carry over for libraries whose series layout is rebuilt.\n\u003e\n\u003e **v0.14.0 Plugin Secret Key**\n\u003e A `PLUGIN_SECRET_KEY` environment variable has been added to encrypt plugin credentials (API keys, tokens, etc.).\n\u003e\n\u003e If not set, a key is auto-generated and saved to `data/.plugin_secret_key`. The server will start without any configuration, but **without the original generated key file, stored plugin credentials cannot be decrypted**. For reliable operation, it is recommended to set `PLUGIN_SECRET_KEY` explicitly in your environment.\n\u003e\n\u003e **v0.10.x Docker update**: Docker base images were changed for CGO/native-library compatibility. Please re-pull the image and recreate the container when updating.\n\u003e\n\u003e **v0.9.0 Security Enhancement \u0026 Breaking Change**\n\u003e For improved security, the container execution privilege has been changed from `root` to a standard user (`appuser`).\n\u003e\n\u003e **Note for existing users**: If thumbnails are broken or you encounter \"Permission Denied\" errors, please ensure you set the `PUID` and `PGID` environment variables to match your account IDs (check with the `id` command in your terminal).\n\n---\n\n## 🇺🇸 What is Kumiho?\n\n**Kumiho** is a self-hosted web media server designed to manage and stream your personal collection of comics and e-books.\n\nIt was originally developed by a developer for personal convenience, after feeling limitations with existing solutions. Written in **Golang**, Kumiho is lightweight and fast.\n\n### ✨ Key Features\n\n| Feature                      | Description                                                                                                                                   |\n| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |\n| **🚀 Blazing Fast**          | Built with Golang, Kumiho runs as a native binary without JVM overhead, offering incredible scan speeds.                                      |\n| **📂 Recursive Leaf Discovery** | It recursively scans nested folders and collects actual readable leaf series without requiring complex metadata matching. |\n| **⚡ Lightweight**           | Optimized for low-resource environments. It runs smoothly with minimal memory footprint.                                                      |\n| **📱 Responsive Viewer**     | Provides a seamless streaming experience on PC, Tablet, and Mobile devices. Supports 'Webtoon' scrolling mode.                                |\n| **🎧 Audiobook Support**     | Supports audiobook libraries with chapter list, resume playback, progress tracking, bookmarks, and sleep timer.                               |\n| **🎵 Immersive BGM**         | Automatically plays audio files (`.mp3`) within the series folder when the filename matches.                                                  |\n\n### Supported Formats\n\n| Category     | Supported Extensions                                                                     |\n| :----------- | :--------------------------------------------------------------------------------------- |\n| **Images**   | `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.bmp`                                         |\n| **Archives** | `.zip`, `.cbz`                                                                           |\n| **E-books**  | `.epub`, `.pdf`, `.txt`                                                                  |\n| **Audio**    | `.mp3`, `.wav`, `.ogg`, `.oga`, `.flac`, `.m4a`, `.m4b`, `.aac`, `.wma`, `.opus`, `.mp4` |\n\n\u003e 📁 **Folder Structure**: Automatically recognizes image files in folders or archive files and organizes them into volumes/chapters.\n\n#### 🔜 Coming Soon\n\n| Category     | Planned Extensions            |\n| :----------- | :---------------------------- |\n| **Archives** | `.cbr`, `.rar`, `.cb7`, `.7z` |\n\n- Support `comicInfo.xml`\n  - Metadata management interaction\n- OPDS Support\n  - Mobile viewer application support\n\n### 📁 Recommended Library Structure\n\n#### 1) Series folder with volume/chapter files directly\n\n```text\n/books\n└── My Series\n    ├── 001.zip\n    ├── 002.pdf\n    └── 003.epub\n```\n\n#### 2) Series folder with chapter/volume subfolders\n\n```text\n/books\n└── My Series\n    ├── Chapter 01\n    │   ├── 001.zip\n    │   └── 002.zip\n    ├── Chapter 02\n    │   └── 001.pdf\n    └── Chapter 03\n        └── 001.epub\n```\n\n#### 3) Nested Folders (Infinite Hierarchy)\n\nKumiho supports **infinite folder hierarchy** through recursive leaf discovery. You can organize your files with any level of subfolders, and Kumiho will scan down to the actual readable leaf series.\n\n```text\n/books\n└── Grand Parent Category\n    └── Parent Category\n        └── My Series\n            ├── Volume 01\n            │   ├── Chapter 01\n            │   │   └── 001.zip\n            │   └── Chapter 02.pdf\n            └── 002.epub\n```\n\nIn the example above, Kumiho uses the nested folders for discovery, then adds the resulting leaf series to the library list instead of rendering the entire folder tree as a separate browse UI.\n\n### 🎵 BGM Auto-Play Rule\n\n- Supported audio formats: `.mp3`, `.ogg`, `.wav`, `.flac`, `.m4a`\n- BGM auto-plays when the audio file has the same base filename as the currently opened volume/chapter file.\n- Example: `001.zip` ↔ `001.mp3`, `001.epub` ↔ `001.mp3`\n\n### 🎧 Audiobook Support\n\n- Supported audiobook formats: `.mp3`, `.wav`, `.ogg`, `.oga`, `.flac`, `.m4a`, `.m4b`, `.aac`, `.wma`, `.opus`, `.mp4`\n- Supports resume playback, chapter-based navigation, progress tracking, bookmarks, and sleep timer\n- Audiobooks can be organized with the same nested folder structure used for books\n- When creating a library for audiobooks, set the library type to **Audiobook**\n\n### 🛠 Installation (Docker)\n\n#### Docker Compose (Recommended)\n\n```yaml\nversion: \"3.8\"\nservices:\n  kumiho:\n    image: ahahyeong/kumiho:latest\n    container_name: kumiho\n    restart: unless-stopped\n    ports:\n      - \"9999:9999\"\n    volumes:\n      - ./data:/app/data # Path to store database and data\n      - ./config:/app/config # Path to store configuration\n      - ./books:/books # Path to your library\n    environment:\n      - PUID=1000 # User ID (Can be found via `id` command)\n      - PGID=1000 # Group ID\n      - TZ=Asia/Seoul\n      - JWT_SECRET=your_secret_key # Recommended for security\n      - PLUGIN_SECRET_KEY=your_plugin_secret_key # Required: without this, plugin credentials cannot be decrypted after reinstall\n```\n\n#### Docker Run\n\n```bash\ndocker run -d \\\n  --name kumiho \\\n  -p 9999:9999 \\\n  -v $(pwd)/data:/app/data \\\n  -v $(pwd)/config:/app/config \\\n  -v $(pwd)/books:/books \\\n  -e PUID=1000 \\\n  -e PGID=1000 \\\n  -e TZ=Asia/Seoul \\\n  -e JWT_SECRET=your_secret_key \\\n  -e PLUGIN_SECRET_KEY=your_plugin_secret_key \\\n  --restart unless-stopped \\\n  ahahyeong/kumiho:latest\n```\n\n### 📂 Library Path Setup Guide\n\nIf you mounted `./books:/books` in your Docker Compose `volumes` configuration, you must enter the **container internal path** `/books` on the Kumiho settings page.\n\n![Library Path Settings](docs/images/library-settings.png)\n\n1. Go to the **Settings \u003e Libraries** tab.\n2. Click the **Add New Library** button.\n3. Enter `/books` in the **Set Path** field. (Do NOT use the host path `./books`!)\n\n\u003e Note: The scanner automatically excludes `@eaDir`, `#recycle`, `.DS_Store`, and `Thumbs.db`.\n\n## 🐞 Bug Reports \u0026 Feature Requests\n\n- [GitHub Issues](https://github.com/aha-hyeong/kumiho/issues)\n- ahahyeong@gmail.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faha-hyeong%2Fkumiho","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faha-hyeong%2Fkumiho","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faha-hyeong%2Fkumiho/lists"}