README
¶
Shisho
Shisho is a self-hosted manager for ebooks, audiobooks, and comics. It provides one library for multiple book formats, metadata management, OPDS and device access, user permissions, and an extensible plugin system.
The Shisho website documentation is the canonical source for setup and configuration guidance for the latest release.
Want to see it before installing? The Public Demo is a read-only instance with a small library of freely redistributable books. Sign in with username demo and password shishodemo.
Why Shisho?
There is no single self-hosted solution that treats ebooks, audiobooks, and comics as equal parts of one library. Audiobook servers and comic servers are excellent for their own media, while ebook managers and their web frontends focus primarily on ebooks. Shisho grew from wanting a self-hosted media server for books that could manage supported formats together instead of treating some of them as secondary.
The goal is a unified library with metadata extraction and editing, optional plugin-based enrichment, manual identification when automation is wrong, Kobo and phone access, and user management for sharing a collection with friends and family.
Quick Start
Docker Compose is the recommended deployment method. The published image supports Linux AMD64 and ARM64.
- Create a working directory and save the following as
docker-compose.yml:
services:
shisho:
image: ghcr.io/shishobooks/shisho:latest
container_name: shisho
restart: unless-stopped
ports:
- "5173:5173"
volumes:
- ./config:/config
# WARNING: This writable mount lets Shisho create covers and sidecars.
# A library's default organization setting can also move and rename media.
- /path/to/your/books:/media
environment:
PUID: "1000"
PGID: "1000"
JWT_SECRET: "${JWT_SECRET:?Set JWT_SECRET before starting Shisho}"
- Replace
/path/to/your/books, then generate a persistent JWT secret:
openssl rand -hex 32
Provide the generated value as JWT_SECRET using your deployment platform's environment or secret-management method. Keep it private and backed up. Changing it invalidates existing sessions.
- Start Shisho:
docker compose up -d
docker compose logs -f shisho
Open http://localhost:5173 and create the first admin account.
Warning: Creating a library immediately queues a scan. Organize file structure during scans is enabled by default for new libraries and can move or rename files on writable media. Back up your media and review that setting before creating the library if you do not want Shisho to reorganize it.
Then create a library whose container path is /media.
DATABASE_FILE_PATH is optional and defaults to /config/shisho.db, so the single /config mount persists the default database, caches, and plugin data.
PUID and PGID select the identity used by the processes inside the container. They do not grant that identity access to the media mount. Configure host ownership and permissions so the selected IDs can read and write the paths Shisho needs.
See Getting Started for the latest released setup guidance. If you are running the current source checkout, use the Unreleased documentation, including Deployment and Maintenance, before exposing or updating the installation.
AI Usage
Shisho does not include an AI service. It has been built with assistance from AI coding tools, with features planned, reviewed, and maintained by the project author. The project started before that tooling was available, but AI assistance made it possible to work on it more consistently around work and life. The architecture, product direction, review, and responsibility for the result remain human-owned.
This disclosure matters because self-hosted users have reasonable concerns about low-quality or unmaintained AI-generated applications. Shisho is developed for a real personal library, and stability and maintainability remain core goals.
Contributing
Before opening a new issue, search the existing issues. Reactions on existing requests help with prioritization. If you want to contribute code, opening an issue first helps align on the approach.
Support
You can support development through Patreon. Shisho remains open source and available for self-hosting.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
api
command
|
|
|
dev
command
Command dev runs the development servers on ports that no other worktree holds.
|
Command dev runs the development servers on ports that no other worktree holds. |
|
migrations
command
|
|
|
scripts/debug/parse-epub
command
|
|
|
scripts/debug/parse-mobi
command
|
|
|
scripts/debug/parse-mp4
command
|
|
|
scripts/debug/print-mp4-atoms
command
|
|
|
internal
|
|
|
devtool
Package devtool runs the development servers so that several worktrees can run them at once without colliding on ports.
|
Package devtool runs the development servers so that several worktrees can run them at once without colliding on ports. |
|
mobigen
Package mobigen builds MOBI, AZW3, and combo files shaped like Calibre's output.
|
Package mobigen builds MOBI, AZW3, and combo files shaped like Calibre's output. |
|
testgen
Package testgen provides utilities for generating test files (EPUB, CBZ, M4B) with configurable metadata for testing the scan worker.
|
Package testgen provides utilities for generating test files (EPUB, CBZ, M4B) with configurable metadata for testing the scan worker. |
|
pkg
|
|
|
covers
Package covers centralizes cover-file selection and serving so that the books, series, ereader, and OPDS handlers don't drift independently.
|
Package covers centralizes cover-file selection and serving so that the books, series, ereader, and OPDS handlers don't drift independently. |
|
ereader
Package ereader serves server-rendered HTML for stock Kobo and Kindle browsers that cannot use OPDS or the React app.
|
Package ereader serves server-rendered HTML for stock Kobo and Kindle browsers that cannot use OPDS or the React app. |
|
filegen/filegentest
Package filegentest holds the conformance suite every filegen.StreamGenerator must pass, and stand-in generators for tests of the download cache and the routes that serve it.
|
Package filegentest holds the conformance suite every filegen.StreamGenerator must pass, and stand-in generators for tests of the download cache and the routes that serve it. |
|
fingerprint
Package fingerprint computes content fingerprints for files.
|
Package fingerprint computes content fingerprints for files. |
|
fingerprints
Package fingerprints provides CRUD operations on the file_fingerprints table.
|
Package fingerprints provides CRUD operations on the file_fingerprints table. |
|
frontend
Package frontend serves the embedded web application.
|
Package frontend serves the embedded web application. |
|
httputil
Package httputil provides small HTTP helpers shared across handlers.
|
Package httputil provides small HTTP helpers shared across handlers. |
|
identifiers
pkg/identifiers/identifiers.go
|
pkg/identifiers/identifiers.go |
|
kepub
Package kepub provides conversion utilities for creating KePub files compatible with Kobo e-readers.
|
Package kepub provides conversion utilities for creating KePub files compatible with Kobo e-readers. |
|
lrufiles
Package lrufiles keeps a directory of cached files within a byte budget by removing the least recently used files first.
|
Package lrufiles keeps a directory of cached files within a byte budget by removing the least recently used files first. |
|
merge
Package merge holds the input checks that every resource merge (People, Series, Genres, Tags, Publishers) runs before it writes anything.
|
Package merge holds the input checks that every resource merge (People, Series, Genres, Tags, Publishers) runs before it writes anything. |
|
mobi
Package mobi reads MOBI and AZW3 files: Mobipocket (MOBI6) books, KF8 books, and combo files that hold a MOBI6 book followed by a KF8 one.
|
Package mobi reads MOBI and AZW3 files: Mobipocket (MOBI6) books, KF8 books, and combo files that hold a MOBI6 book followed by a KF8 one. |
|
pdf/incremental
Package incremental reads just enough of a PDF to append an incremental update to it, and writes that update.
|
Package incremental reads just enough of a PDF to append an incremental update to it, and writes that update. |
|
seriesnum
Package seriesnum parses and formats single series numbers and contiguous ranges.
|
Package seriesnum parses and formats single series numbers and contiguous ranges. |
|
sharelinks
Package sharelinks holds the Share Link feature: anonymous, expiring links that grant access to one Book.
|
Package sharelinks holds the Share Link feature: anonymous, expiring links that grant access to one Book. |
|
sortname
Package sortname provides functions for generating bibliographic sort names following ALA/Library of Congress conventions.
|
Package sortname provides functions for generating bibliographic sort names following ALA/Library of Congress conventions. |
|
sortspec
Package sortspec parses, validates, builds SQL for, and resolves multi-level sort specifications (e.g.
|
Package sortspec parses, validates, builds SQL for, and resolves multi-level sort specifications (e.g. |
|
sqliteconn
Package sqliteconn opens SQLite connections that run a fixed set of statements, usually pragmas, on every connection the pool opens, and provides the bun dialect for them.
|
Package sqliteconn opens SQLite connections that run a fixed set of statements, usually pragmas, on every connection the pool opens, and provides the bun dialect for them. |
|
testutils
Package testutils provides test-only API endpoints.
|
Package testutils provides test-only API endpoints. |
|
testutils/goconsts
Package goconsts reads string constants out of Go source so a test can check that every constant of a family is handled, without a hand-kept list that goes stale the same way the code under test would.
|
Package goconsts reads string constants out of Go source so a test can check that every constant of a family is handled, without a hand-kept list that goes stale the same way the code under test would. |
|
testutils/testdb
Package testdb opens the database that package tests run against.
|
Package testdb opens the database that package tests run against. |
|
testutils/testumask
Package testumask sets the process umask for the length of a test.
|
Package testumask sets the process umask for the length of a test. |
|
ziputil
Package ziputil writes zip entries without recompressing them, for generators that stream an archive built from another one.
|
Package ziputil writes zip entries without recompressing them, for generators that stream an archive built from another one. |
|
tools
|
|
|
checkdocrefs
command
Command checkdocrefs fails when an agent instruction file (every AGENTS.md, CODING_STANDARDS.md, and docs/agents/**/*.md) names a repo path, code identifier, or quoted section that no longer exists.
|
Command checkdocrefs fails when an agent instruction file (every AGENTS.md, CODING_STANDARDS.md, and docs/agents/**/*.md) names a repo path, code identifier, or quoted section that no longer exists. |
|
checkversions
command
Command checkversions fails when a tool pinned in mise.toml is pinned to a different version in the Dockerfile (golang and node base images, the tygo `go install`) or package.json (packageManager pnpm, the @types/node major).
|
Command checkversions fails when a tool pinned in mise.toml is pinned to a different version in the Dockerfile (golang and node base images, the tygo `go install`) or package.json (packageManager pnpm, the @types/node major). |
|
gotestsplit
command
Package main is gotestsplit, a timing-aware fork of gotesplit (https://github.com/Songmu/gotesplit, MIT).
|
Package main is gotestsplit, a timing-aware fork of gotesplit (https://github.com/Songmu/gotesplit, MIT). |