From aradotso-trending-skills-37
Guides Docker-based installation, configuration, and extension of Grimmory self-hosted book library manager supporting EPUBs, PDFs, comics, Kobo/OPDS sync, multi-user.
npx claudepluginhub joshuarweaver/cascade-ai-ml-agents-misc-1 --plugin aradotso-trending-skills-37This skill uses the workspace's default tool permissions.
> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Generates original PNG/PDF visual art via design philosophy manifestos for posters, graphics, and static designs on user request.
Skill by 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.
.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
docker-compose.ymlservices:
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
docker compose up -d
# View logs
docker compose logs -f grimmory
# Check health
curl http://localhost:6060/api/v1/healthcheck
Open http://localhost:6060 and create your admin account.
./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
| 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 |
| Category | Formats |
|---|---|
| eBooks | EPUB, MOBI, AZW, AZW3 |
| Documents | |
| Comics | CBZ, CBR, CB7 |
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:
/bookdrop continuouslyVolume mapping required in docker-compose.yml:
volumes:
- ./bookdrop:/bookdrop
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
Grimmory is a Java application (Spring Boot + MariaDB). When contributing or extending:
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
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
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();
}
}
}
@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));
}
}
@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;
}
@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);
}
}
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.
Create users from the admin panel at http://localhost:6060. Each user has isolated shelves, reading progress, and preferences.
Configure via environment variables (refer to full documentation at https://grimmory.org/docs/getting-started for OIDC-specific variables such as OIDC_ISSUER_URI, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET).
# 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: .'
# 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
# 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
# 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
# Set ownership to match APP_USER_ID / APP_GROUP_ID
sudo chown -R 1000:1000 ./books ./data ./bookdrop
# Confirm port 6060 is reachable from your device
curl http://<host-ip>:6060/api/v1/healthcheck
# Check firewall rules if on a remote server
MariaDB and Grimmory together require at minimum ~512 MB RAM. For large libraries (10k+ books), allocate 1–2 GB.
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"
Before opening a pull request:
CONTRIBUTING.md# Run tests before submitting
./mvnw test
# Check code style
./mvnw checkstyle:check
ghcr.io/grimmory-tools/grimmory