鶴読み Tsuruyomi

Ultra-fast, lightweight native Go backend replacement for Suwayomi-Server (Tachidesk) with OPDS 1.2

---

⚡ Performance Benchmarks

Metric	Suwayomi-Server (Java JVM)	Tsuruyomi (Go)	Improvement
Idle Memory (RAM)	~1,200 MB – 1,800 MB	~35 MB – 50 MB	> 95% less RAM
Cold Startup Time	~22 – 30 seconds	~45 milliseconds	~500x faster
Library Query (1,500+ series)	~1,200 ms (or crashes with SQL 500)	~25 ms	~48x faster
Runtime Dependency	OpenJDK 17/21 JRE (~300MB)	Zero (Static Native Binary)	Self-contained
OPDS Stability	❌ SQL GROUP BY bug in Exposed ORM	✅ Native SQL, zero crashes	Rock-solid

---

🌟 Key Features

• Blazingly Fast & Lightweight: Written in Go with Fiber and pgx, using under 50 MB of RAM. Perfect for Raspberry Pi, LXC containers, NAS devices, and low-spec VPS.
• Native OPDS 1.2 Server:
  • Full navigation feeds: All Series, Categories, Sources, Genres, Publication Statuses, Recent Updates, Reading History.
  • OPDS Page Streaming (PSE): Stream individual chapter pages without downloading the entire CBZ archive.
  • Open-Access CBZ Acquisition: Download chapters as .cbz directly to e-readers.
  • Automatic Read Status: Sync reading progress via ?markAsRead=true or OPDS-PSE headers.
  • OpenSearch XML discovery description.
• Full API Compatibility:
  • /api/v1/... REST API (Manga, Chapters, Categories, Downloads, Updates, Backups).
  • /api/graphql endpoint for complete compatibility with Tachidesk-WebUI and external clients.
  • Real-time WebSockets for download queue progress and library batch updates.
• Native Go Scrapers & JavaScript Engine:
  • Direct high-speed scrapers for popular sources (MangaDex, LectorManga, Madara engines, MangaThemesia).
  • Built-in Goja JavaScript runtime to load community extensions without a JVM.
  • Optional JVM sidecar fallback proxy for unmigrated legacy extensions.
• Cloudflare Bypass: Native integration with FlareSolverr to solve Cloudflare Turnstile / anti-bot challenges seamlessly.
• Bundled WebUI: Includes the complete, responsive Tachidesk-WebUI preconfigured with the Tsuruyomi Crimson palette (#E11D48) and Origami Crane launcher icons.

---

📱 Compatible Clients & E-Readers

Client / Reader	Platform	Connection Mode
Tachidesk WebUI	Web Browser / PWA	Native HTTP / GraphQL
Moon+ Reader	Android	OPDS Catalog (http://<ip>:7654/opds)
KOReader	Kobo, Kindle, Android, Linux	OPDS Catalog (http://<ip>:7654/opds)
Chunky Comic Reader	iOS / iPadOS	OPDS Catalog (http://<ip>:7654/opds)
Panels	iOS / iPadOS	OPDS Catalog (http://<ip>:7654/opds)
Mihon / Tachiyomi	Android	Tachidesk Extension

---

🚀 Quick Start

1. Download or Build from Source

Requirements

• Go 1.24+ (if compiling from source)
• PostgreSQL 14+ (or existing Suwayomi database)

Build Binary

# Clone the repository
git clone https://github.com/devil1210/tsuruyomi.git
cd tsuruyomi

# Build for current OS
go build -o tsuruyomi ./cmd/server

# Cross-compile for Linux AMD64
GOOS=linux GOARCH=amd64 go build -o tsuruyomi ./cmd/server

2. Configuration

Copy config.example.yaml to config.yaml and configure your database connection:

cp config.example.yaml config.yaml

server:
  host: "0.0.0.0"
  port: 7654
  subpath: ""

database:
  dsn: "postgres://username:password@localhost:5432/suwayomi?sslmode=disable"
  max_conns: 20
  min_conns: 2

data:
  root_dir: "./data"

auth:
  mode: "none" # "none", "basic", or "simple_login"

flaresolverr:
  enabled: false
  url: "http://127.0.0.1:8191"
  timeout: 90

3. Run

./tsuruyomi -config config.yaml

Once running, access:

• Web Interface: http://localhost:7654
• OPDS Catalog: http://localhost:7654/opds or http://localhost:7654/api/opds/v1.2
• API Status: http://localhost:7654/api/v1/settings/about

---

🐳 Docker Deployment

Docker Compose

version: '3.8'

services:
  tsuruyomi:
    image: tsuruyomi:latest
    container_name: tsuruyomi
    restart: unless-stopped
    ports:
      - "7654:7654"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
      - ./data:/app/data
    environment:
      - SUWAYOMI_SERVER_PORT=7654
    depends_on:
      - postgres

  postgres:
    image: postgres:16-alpine
    container_name: tsuruyomi-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: suwayomi
      POSTGRES_USER: tsuruyomi
      POSTGRES_PASSWORD: secretpassword
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

---

📖 OPDS Reader Configuration

To connect e-readers such as KOReader or Moon+ Reader:

1. Open your reader's OPDS / Net Library section.
2. Add a new catalog:
   • Name: Tsuruyomi
   • URL: http://<your-server-ip>:7654/opds (or http://<your-server-ip>:7654/api/opds/v1.2)
   • Username / Password: (Leave blank unless Basic Auth is enabled in config.yaml)
3. Save and open the catalog. You will have full access to your manga library, categories, search, reading history, and direct CBZ downloading.

---

📄 License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for details.

---

🤝 Acknowledgments

• Suwayomi-Server / Tachidesk for the original specification and GraphQL schema.
• Mihon & Tachiyomi community for the extension ecosystem.