Docker volumes:

Previously /books pointed to /opt/shelfmark/books (isolated from Readarr). Changed 2026-03-31 to /mnt/seedbox/Books so Shelfmark downloads land directly in the seedbox Books folder where Readarr can see them.

Docker environment:

PROXY_MODE=socks5
SOCKS5_PROXY=socks5://172.25.0.1:1080
NO_PROXY=localhost,127.0.0.1,192.168.8.*,172.25.0.*
TZ=America/New_York
PUID=0
PGID=0

PUID/PGID set to 0 (root): The seedbox Books folder receives files via rsync with UID 1040, which Shelfmark’s default appuser (UID 1000) cannot write to. Running as root prevents “destination not writable” errors during post-processing. Changed 2026-04-02.

Shelfmark routes all search and download traffic through the seedbox to avoid region-based restrictions. The chain is:

Shelfmark (CT 100 Docker)
    ↓ SOCKS5 to 172.25.0.1:1080 (Docker bridge → CT 100 host)
seedbox-socks.service (autossh, CT 100 systemd)
    ↓ SSH tunnel to delgross@46.232.210.50
ismene.usbx.me (Netherlands exit, UltraSeedbox)
    ↓
Book search sources (Anna's Archive, Libgen, etc.)

Check proxy tunnel status:

# SSH into CT 100 first
ssh root@192.168.8.221
pct exec 100 -- bash
# Then:
systemctl status seedbox-socks.service

Restart proxy tunnel:

systemctl restart seedbox-socks.service

If Shelfmark searches fail or time out: The SOCKS5 tunnel is almost always the culprit. Check the service status above. The tunnel reconnects automatically via autossh, but occasionally needs a manual restart after seedbox connectivity issues.

Prowlarr runs on CT100 as an indexer aggregator, providing Usenet-based book search as an additional release source alongside the direct download sources (Anna’s Archive, Libgen, etc.). Prowlarr routes all traffic through the same SOCKS5 seedbox tunnel as Shelfmark.

Indexers configured:

Shelfmark connection: Enabled in Shelfmark Settings → Prowlarr with auto-expand search on. When Shelfmark searches for a book, it queries both direct_download and prowlarr sources simultaneously. Prowlarr found 115 additional books that direct download sources couldn’t locate.

Note: Prowlarr’s Docker network (prowlarr_default) uses gateway 172.26.0.1, which is different from Shelfmark’s network (shelfmark_default, gateway 172.25.0.1). Both reach the same SOCKS tunnel on 0.0.0.0:1080 on the CT100 host, just via different Docker bridge IPs.

A Python script at ~/Sync/ED/homelab/book_library/kindle_to_shelfmark.py automates bulk importing from the Kindle library into Shelfmark. It reads the Kindle NZB results JSON (1,773 books with titles, authors, and ASINs) and for each book: searches Shelfmark’s Hardcover metadata provider, finds downloadable releases, and queues the best epub for download.

First full run (2026-03-31):

Usage:

cd ~/Sync/ED/homelab/book_library

# Dry run — search only, don't download
python3 kindle_to_shelfmark.py --dry-run --skip-existing

# Full run — queue all downloads
python3 kindle_to_shelfmark.py --skip-existing --delay 5

# Resume after interruption
python3 kindle_to_shelfmark.py --skip-existing --resume

# Process in batches
python3 kindle_to_shelfmark.py --skip-existing --limit 50

Files:

How the script works:

1. For each Kindle book, search Shelfmark metadata API (/api/metadata/search) using title + author
2. Find best match by title word overlap (≥40% threshold)
3. Search for downloadable releases (/api/releases) using the matched provider/book_id
4. Score releases — prefer epub format, reasonable file size (0.5–100 MB)
5. Queue the best release via /api/releases/download
6. Save state after every 20 books for resume capability

Shelfmark has no authentication enabled (auth_mode: none). All API endpoints are accessible without credentials.

Shelfmark searches multiple sources in priority order until a download succeeds.

Fast sources (tried first):

Slow sources (fallback):

Additional sources:

Anna’s Archive donator key is configured in Settings → Download Sources. This unlocks the AA Fast Downloads tier with dedicated servers instead of the free mirrors that crawl at 3-10 KB/s.

DNS-over-HTTPS (DoH) is disabled in Shelfmark’s network config (/opt/shelfmark/config/plugins/network.json, USE_DOH: false). DoH via Quad9 was returning 400 errors for several domains when routed through the SOCKS tunnel, causing all post-processing to fail. System DNS resolution works correctly as a fallback.

Shelfmark is configured as a Pangolin private resource — it’s reachable remotely without opening any public ports. Connect via the Pangolin VPN client and access it at http://192.168.8.100:8084 as if you’re on the home network.

It does not have a public subdomain — intentionally kept private since it’s a search aggregation tool.

Shelfmark is one of three book-related services in the stack:

All three share the seedbox Books folder (nvmepool/ingest → /mnt/seedbox/Books on CT 100). Shelfmark downloads to it, Readarr imports from it, and the existing library of ~512 books lives there.