---
id: daily-grimmory-self-hosted-library
name: "grimmory-self-hosted-library"
url: https://skills.yangsir.net/skill/daily-grimmory-self-hosted-library
author: aradotso
domain: lifestyle
tags: ["self-hosted", "ebook-management", "media-library", "calibre-alternative", "personal-knowledge-base"]
install_count: 1100
rating: 4.30 (20 reviews)
github: https://github.com/aradotso/trending-skills
---

# grimmory-self-hosted-library

> 自托管电子书管理工具，支持 EPUB、PDF、MOBI、漫画等多种格式，提供元数据管理和阅读进度追踪

**Stats**: 1,100 installs · 4.3/5 (20 reviews)

## Before / After 对比

### 电子书管理对比

**Before**:

电子书分散在各类文件夹和云盘中，文件名混乱，缺少封面和元数据，搜索困难，阅读进度无法同步

**After**:

统一管理界面自动抓取书籍元数据和封面，支持全文搜索、标签分类、阅读进度同步，一键导入千本电子书

| Metric | Before | After | Change |
|---|---|---|---|
| 检索时间 | 5分钟 | 0.3分钟 | -94% |

## Readme

# grimmory-self-hosted-library

# Grimmory Self-Hosted Library Manager

Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Grimmory is a self-hosted application (successor to BookLore) for managing your entire book collection. It supports EPUBs, PDFs, MOBIs, AZW/AZW3, and comics (CBZ/CBR/CB7), with a built-in browser reader, annotations, Kobo/OPDS sync, KOReader progress sync, metadata enrichment, and multi-user support.

## Installation

### Requirements

- Docker and Docker Compose

### Step 1: Create `.env`

```
# Application
APP_USER_ID=1000
APP_GROUP_ID=1000
TZ=Etc/UTC

# Database
DATABASE_URL=jdbc:mariadb://mariadb:3306/grimmory
DB_USER=grimmory
DB_PASSWORD=${DB_PASSWORD}

# Storage: LOCAL (default) or NETWORK
DISK_TYPE=LOCAL

# MariaDB
DB_USER_ID=1000
DB_GROUP_ID=1000
MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
MYSQL_DATABASE=grimmory

```

### Step 2: Create `docker-compose.yml`

```
services:
  grimmory:
    image: grimmory/grimmory:latest
    # Alternative registry: ghcr.io/grimmory-tools/grimmory:latest
    container_name: grimmory
    environment:
      - USER_ID=${APP_USER_ID}
      - GROUP_ID=${APP_GROUP_ID}
      - TZ=${TZ}
      - DATABASE_URL=${DATABASE_URL}
      - DATABASE_USERNAME=${DB_USER}
      - DATABASE_PASSWORD=${DB_PASSWORD}
      - DISK_TYPE=${DISK_TYPE}
    depends_on:
      mariadb:
        condition: service_healthy
    ports:
      - "6060:6060"
    volumes:
      - ./data:/app/data
      - ./books:/books
      - ./bookdrop:/bookdrop
    healthcheck:
      test: wget -q -O - http://localhost:6060/api/v1/healthcheck
      interval: 60s
      retries: 5
      start_period: 60s
      timeout: 10s
    restart: unless-stopped

  mariadb:
    image: lscr.io/linuxserver/mariadb:11.4.5
    container_name: mariadb
    environment:
      - PUID=${DB_USER_ID}
      - PGID=${DB_GROUP_ID}
      - TZ=${TZ}
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
      - MYSQL_DATABASE=${MYSQL_DATABASE}
      - MYSQL_USER=${DB_USER}
      - MYSQL_PASSWORD=${DB_PASSWORD}
    volumes:
      - ./mariadb/config:/config
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "mariadb-admin", "ping", "-h", "localhost"]
      interval: 5s
      timeout: 5s
      retries: 10

```

### Step 3: Launch

```
docker compose up -d

# View logs
docker compose logs -f grimmory

# Check health
curl http://localhost:6060/api/v1/healthcheck

```

Open [http://localhost:6060](http://localhost:6060) and create your admin account.

## Volume Layout

```
./data/          # App data, thumbnails, user config
./books/         # Your book files (mounted at /books)
./bookdrop/      # Drop-zone for auto-import (mounted at /bookdrop)
./mariadb/       # MariaDB data

```

## Environment Variables Reference

Variable
Description
Default

`USER_ID`
UID for the app process
`1000`

`GROUP_ID`
GID for the app process
`1000`

`TZ`
Timezone string
`Etc/UTC`

`DATABASE_URL`
JDBC connection string
required

`DATABASE_USERNAME`
DB username
required

`DATABASE_PASSWORD`
DB password
required

`DISK_TYPE`
`LOCAL` or `NETWORK`
`LOCAL`

## Supported Book Formats

Category
Formats

eBooks
EPUB, MOBI, AZW, AZW3

Documents
PDF

Comics
CBZ, CBR, CB7

## BookDrop (Auto-Import)

Drop files into `./bookdrop/` on your host. Grimmory watches the folder, extracts metadata from Google Books and Open Library, and queues books for review.

```
./bookdrop/
  my-novel.epub        ← dropped here
  another-book.pdf     ← dropped here

```

Flow:

- **Watch** — Grimmory monitors `/bookdrop` continuously

- **Detect** — New files are picked up and parsed

- **Enrich** — Metadata fetched from Google Books / Open Library

- **Import** — Review in UI, adjust if needed, confirm import

Volume mapping required in `docker-compose.yml`:

```
volumes:
  - ./bookdrop:/bookdrop

```

## Network Storage Mode

For NFS, SMB, or other network-mounted filesystems, set `DISK_TYPE=NETWORK`. This disables destructive UI operations (delete, move, rename) to protect shared mounts while keeping reading, metadata, and sync fully functional.

```
# .env
DISK_TYPE=NETWORK

```

## Java Backend — Key Patterns

Grimmory is a Java application (Spring Boot + MariaDB). When contributing or extending:

### Project Structure (typical Spring Boot layout)

```
src/main/java/
  com/grimmory/
    config/          # Spring configuration classes
    controller/      # REST API controllers
    service/         # Business logic
    repository/      # JPA repositories
    model/           # JPA entities
    dto/             # Data transfer objects

```

### REST API — Base Path

All endpoints are under `/api/v1/`:

```
# Health check
GET http://localhost:6060/api/v1/healthcheck

# Books
GET http://localhost:6060/api/v1/books
GET http://localhost:6060/api/v1/books/{id}
POST http://localhost:6060/api/v1/books
PUT http://localhost:6060/api/v1/books/{id}
DELETE http://localhost:6060/api/v1/books/{id}

# Shelves
GET http://localhost:6060/api/v1/shelves
POST http://localhost:6060/api/v1/shelves

# OPDS catalog (for compatible reader apps)
GET http://localhost:6060/opds

```

### Example: Querying the API with Java (OkHttp)

```
import okhttp3.*;
import com.fasterxml.jackson.databind.ObjectMapper;

public class GrimmoryClient {

    private final OkHttpClient http = new OkHttpClient();
    private final ObjectMapper mapper = new ObjectMapper();
    private final String baseUrl;
    private final String token;

    public GrimmoryClient(String baseUrl, String token) {
        this.baseUrl = baseUrl;
        this.token = token;
    }

    public String getBooks() throws Exception {
        Request request = new Request.Builder()
            .url(baseUrl + "/api/v1/books")
            .header("Authorization", "Bearer " + token)
            .build();

        try (Response response = http.newCall(request).execute()) {
            return response.body().string();
        }
    }
}

```

### Example: Spring Boot Controller Pattern

```
@RestController
@RequestMapping("/api/v1/books")
@RequiredArgsConstructor
public class BookController {

    private final BookService bookService;

    @GetMapping
    public ResponseEntity<Page<BookDto>> getAllBooks(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size,
            @RequestParam(required = false) String search) {
        return ResponseEntity.ok(bookService.findAll(page, size, search));
    }

    @GetMapping("/{id}")
    public ResponseEntity<BookDto> getBook(@PathVariable Long id) {
        return ResponseEntity.ok(bookService.findById(id));
    }

    @PostMapping
    public ResponseEntity<BookDto> createBook(@RequestBody @Valid CreateBookRequest request) {
        return ResponseEntity.status(HttpStatus.CREATED)
                .body(bookService.create(request));
    }

    @PutMapping("/{id}/metadata")
    public ResponseEntity<BookDto> updateMetadata(
            @PathVariable Long id,
            @RequestBody @Valid UpdateMetadataRequest request) {
        return ResponseEntity.ok(bookService.updateMetadata(id, request));
    }
}

```

### Example: JPA Entity Pattern

```
@Entity
@Table(name = "books")
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Book {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String title;

    private String author;
    private String isbn;
    private String format;  // EPUB, PDF, CBZ, etc.

    @Column(name = "file_path")
    private String filePath;

    @Column(name = "cover_path")
    private String coverPath;

    @Column(name = "reading_progress")
    private Double readingProgress;

    @ManyToMany
    @JoinTable(
        name = "book_shelf",
        joinColumns = @JoinColumn(name = "book_id"),
        inverseJoinColumns = @JoinColumn(name = "shelf_id")
    )
    private Set<Shelf> shelves = new HashSet<>();

    @CreationTimestamp
    private LocalDateTime createdAt;

    @UpdateTimestamp
    private LocalDateTime updatedAt;
}

```

### Example: Service with Metadata Enrichment

```
@Service
@RequiredArgsConstructor
public class MetadataService {

    private final GoogleBooksClient googleBooksClient;
    private final OpenLibraryClient openLibraryClient;
    private final BookRepository bookRepository;

    public BookDto enrichMetadata(Long bookId) {
        Book book = bookRepository.findById(bookId)
            .orElseThrow(() -> new BookNotFoundException(bookId));

        // Try Google Books first
        Optional<BookMetadata> metadata = googleBooksClient.search(book.getTitle(), book.getAuthor());

        // Fall back to Open Library
        if (metadata.isEmpty()) {
            metadata = openLibraryClient.search(book.getIsbn());
        }

        metadata.ifPresent(m -> {
            book.setDescription(m.getDescription());
            book.setCoverUrl(m.getCoverUrl());
            book.setPublisher(m.getPublisher());
            book.setPublishedDate(m.getPublishedDate());
            bookRepository.save(book);
        });

        return BookDto.from(book);
    }
}

```

## OPDS Integration

Connect any OPDS-compatible reader app (Kybook, Chunky, Moon+ Reader, etc.) using:

```
http://<your-host>:6060/opds

```

Authenticate with your Grimmory username and password when prompted.

## Kobo / KOReader Sync

- **Kobo**: Connect via the device sync feature in Grimmory settings. The app exposes a sync endpoint compatible with Kobo's API.

- **KOReader**: Configure KOReader's sync plugin to point to your Grimmory instance URL.

## Multi-User & Authentication

### Local Authentication

Create users from the admin panel at [http://localhost:6060](http://localhost:6060). Each user has isolated shelves, reading progress, and preferences.

### OIDC Authentication

Configure via environment variables (refer to full documentation at [https://grimmory.org/docs/getting-started](https://grimmory.org/docs/getting-started) for OIDC-specific variables such as `OIDC_ISSUER_URI`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`).

## Building from Source

```
# Clone the repository
git clone https://github.com/grimmory-tools/grimmory.git
cd grimmory

# Build with Maven
./mvnw clean package -DskipTests

# Or build Docker image locally
docker build -t grimmory:local .

# Use local build in docker-compose.yml
# Comment out 'image' and uncomment 'build: .'

```

## Common Docker Commands

```
# Start services
docker compose up -d

# Stop services
docker compose down

# View app logs
docker compose logs -f grimmory

# View DB logs
docker compose logs -f mariadb

# Restart only the app
docker compose restart grimmory

# Pull latest image and redeploy
docker compose pull && docker compose up -d

# Open a shell inside the container
docker exec -it grimmory /bin/bash

# Database shell
docker exec -it mariadb mariadb -u grimmory -p grimmory

```

## Troubleshooting

### Container won't start — DB connection refused

```
# Check MariaDB health
docker compose ps mariadb
# Should show "healthy". If not:
docker compose logs mariadb
# Ensure DATABASE_URL host matches the service name: mariadb:3306

```

### Books not appearing after BookDrop

```
# Verify file permissions — UID/GID must match APP_USER_ID/APP_GROUP_ID
ls -la ./bookdrop/
# Check app logs for detection events
docker compose logs -f grimmory | grep -i bookdrop

```

### Permission denied on ./books or ./data

```
# Set ownership to match APP_USER_ID / APP_GROUP_ID
sudo chown -R 1000:1000 ./books ./data ./bookdrop

```

### OPDS not accessible from reader app

```
# Confirm port 6060 is reachable from your device
curl http://<host-ip>:6060/api/v1/healthcheck
# Check firewall rules if on a remote server

```

### High memory usage

MariaDB and Grimmory together require at minimum ~512 MB RAM. For large libraries (10k+ books), allocate 1–2 GB.

### Metadata not enriching

Google Books and Open Library require outbound internet access from the container. Verify DNS and network:

```
docker exec -it grimmory curl -s "https://www.googleapis.com/books/v1/volumes?q=test"

```

## Contributing

Before opening a pull request:

- Open an issue and get maintainer approval

- Include screenshots/video proof and pasted test output

- Follow backend and frontend conventions in `CONTRIBUTING.md`

- AI-assisted code is allowed but you must run, test, and understand every line

```
# Run tests before submitting
./mvnw test

# Check code style
./mvnw checkstyle:check

```

## Links

- **GitHub**: [https://github.com/grimmory-tools/grimmory](https://github.com/grimmory-tools/grimmory)

- **Docker Hub**: [https://hub.docker.com/r/grimmory/grimmory](https://hub.docker.com/r/grimmory/grimmory)

- **GHCR**: `ghcr.io/grimmory-tools/grimmory`

- **Discord**: [https://discord.gg/FwqHeFWk](https://discord.gg/FwqHeFWk)

- **Docs**: [https://grimmory.org/docs/getting-started](https://grimmory.org/docs/getting-started)

- **License**: AGPL-3.0

Weekly Installs255Repository[aradotso/trending-skills](https://github.com/aradotso/trending-skills)GitHub Stars10First Seen7 days agoSecurity Audits[Gen Agent Trust HubPass](/aradotso/trending-skills/grimmory-self-hosted-library/security/agent-trust-hub)[SocketPass](/aradotso/trending-skills/grimmory-self-hosted-library/security/socket)[SnykWarn](/aradotso/trending-skills/grimmory-self-hosted-library/security/snyk)Installed ongithub-copilot254codex254warp254amp254cline254kimi-cli254

---
*Source: https://skills.yangsir.net/skill/daily-grimmory-self-hosted-library*
*Markdown mirror: https://skills.yangsir.net/api/skill/daily-grimmory-self-hosted-library/markdown*