a303538ae5
Agent skill doc covering the full Calibre library workflow: importing books via Unraid Docker containers, metadata management, tag rules, KOReader OPDS access on Boox, and external serving options.
122 lines
4.6 KiB
Markdown
122 lines
4.6 KiB
Markdown
# Calibre Book Import Workflow
|
|
|
|
## Library Setup
|
|
|
|
The Calibre library lives on an **Unraid server** with two Docker containers:
|
|
- **linuxserver/calibre** — full desktop GUI, accessible via browser (for manual imports/editing)
|
|
- **linuxserver/calibre-web** — web reader frontend for reading books
|
|
|
|
Library path on Unraid: `/mnt/user/la-share/home/books/calibre_library/`
|
|
|
|
### Docker permissions
|
|
- Containers should use `PUID=99` and `PGID=100` (maps to `nobody:users`)
|
|
- If SMB write issues occur: `chown -R nobody:users /mnt/user/la-share/home/books/calibre_library/`
|
|
|
|
## Importing New Books
|
|
|
|
### Option 1: Calibre GUI container (recommended for routine imports)
|
|
1. Upload new book files to Unraid (via copyparty or SMB)
|
|
2. Open the Calibre GUI container in browser
|
|
3. Drag and drop to import, edit metadata, fetch covers
|
|
|
|
### Option 2: With Claude's help (for bulk imports or metadata cleanup)
|
|
1. Upload new book files to Unraid
|
|
2. Import into the Calibre GUI container
|
|
3. Ask Claude to generate `calibredb` commands for metadata fixes
|
|
4. Run commands via Unraid terminal or `docker exec`:
|
|
```bash
|
|
docker exec calibre calibredb list --library-path /config/library
|
|
docker exec calibre calibredb set_metadata <id> -f title:"Title" --library-path /config/library
|
|
```
|
|
(Adjust container name and library path as needed)
|
|
|
|
### Option 3: Local import then sync (for large batches)
|
|
1. Import and fix metadata locally on Mac using CLI tools at `/Applications/calibre.app/Contents/MacOS/`
|
|
2. Copy the specific book folders + updated `metadata.db` to Unraid via copyparty
|
|
3. Stop containers before overwriting `metadata.db`, restart after
|
|
|
|
## Import Steps (Detail)
|
|
|
|
### 1. List files to import
|
|
Show file names, sizes, and formats from the source folder.
|
|
|
|
### 2. Check for duplicates
|
|
```bash
|
|
# Local
|
|
sqlite3 "$HOME/Calibre Library/metadata.db" "SELECT id, title FROM books ORDER BY title;"
|
|
|
|
# Or on Unraid
|
|
docker exec calibre calibredb list --library-path /config/library
|
|
```
|
|
|
|
### 3. Fetch metadata (do NOT import yet)
|
|
```bash
|
|
fetch-ebook-metadata -t "Title" -a "Author"
|
|
```
|
|
Uses 3 plugins: New Douban Books, Google Books, Amazon.com.
|
|
|
|
If not found online, read embedded metadata:
|
|
- `ebook-meta file.epub` (often has good embedded data)
|
|
- `ebook-convert file.pdf /tmp/out.txt` (extract text to identify unknown files)
|
|
|
|
### 4. Show complete metadata for approval
|
|
Present ALL metadata for ALL books before importing:
|
|
- Title, Author(s), Publisher, Tags, ISBN
|
|
|
|
**Wait for explicit approval before proceeding.**
|
|
|
|
### 5. Import
|
|
```bash
|
|
calibredb add "file.epub" --library-path "$LIB"
|
|
```
|
|
|
|
For multi-format books (same book in epub + mobi + pdf):
|
|
- Import the first format with `calibredb add`
|
|
- Add additional formats with `calibredb add_format <id> <file>`
|
|
- Do NOT pass all formats to `calibredb add` at once — it creates separate entries
|
|
|
|
### 6. Apply metadata
|
|
```bash
|
|
calibredb set_metadata <id> \
|
|
-f title:"Book Title" \
|
|
-f authors:"Author Name" \
|
|
-f publisher:"Publisher" \
|
|
-f tags:"tag1,tag2,tag3" \
|
|
-f identifiers:"isbn:1234567890" \
|
|
-f series:"Series Name" \
|
|
-f series_index:"1" \
|
|
--library-path "$LIB"
|
|
```
|
|
|
|
### 7. Verify and clean up
|
|
- Check for split entries — merge with `add_format` + `remove`
|
|
- Verify titles, authors, tags are correct
|
|
- Delete source files after successful import
|
|
|
|
## Tag Rules
|
|
|
|
- **Chinese tags for Chinese books** — never English equivalents
|
|
- **No publisher/author/year/title as tags** — use their dedicated fields
|
|
- **No overly generic tags** — avoid 经典, 中国, 人文, 入门, 教程, 参考
|
|
- **Consolidate similar tags** — check existing tags before creating new ones
|
|
|
|
## Reading on Boox (KOReader + OPDS)
|
|
|
|
Calibre-web serves an OPDS catalog automatically. KOReader on Boox has built-in OPDS support.
|
|
|
|
### Setup
|
|
1. Open KOReader → **Search** (magnifying glass) → **OPDS catalog**
|
|
2. Add a new catalog: `http://UNRAID_IP:8083/opds` (adjust port to match Calibre-web)
|
|
3. Browse library, tap a book to download directly to the e-reader
|
|
|
|
### Reading strategy
|
|
- **KOReader** for books — optimized for e-ink, great typography control, PDF reflow, offline dictionary
|
|
- **Readwise Reader** for articles, RSS, newsletters — highlight sync, cross-device reading
|
|
|
|
## Serving Externally
|
|
|
|
Options for accessing the library outside the home network:
|
|
- **Tailscale** (recommended) — install on Unraid (community plugin) + Boox (Android app). Access Calibre-web OPDS via Tailscale IP: `http://100.x.x.x:8083/opds`. Free tier supports 100 devices.
|
|
- **Cloudflare Tunnel** — free, no open ports, gives public URL like `books.yourdomain.com`
|
|
- **Reverse proxy** — Nginx Proxy Manager + domain, requires port 443 open
|