[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-72335":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":9,"languages":8,"totalLinesOfCode":8,"stars":10,"forks":11,"watchers":12,"openIssues":13,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":14,"forks30d":14,"starsTrendScore":18,"compositeScore":19,"rankGlobal":8,"rankLanguage":8,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":8,"pushedAt":8,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":14,"starSnapshotCount":14,"syncStatus":28,"lastSyncTime":29,"discoverSource":30},72335,"shelfmark","calibrain\u002Fshelfmark","calibrain",null,"Python",3346,175,12,49,0,28,77,178,84,105.74,"MIT License",false,"main",true,[],"2026-06-12 04:01:04","# 📚 Shelfmark: Book Search & Request Tool\n\n\u003Cimg src=\"src\u002Ffrontend\u002Fpublic\u002Flogo.png\" alt=\"Shelfmark\" width=\"200\">\n\n> [!NOTE]\n> This project is in a stable state as of May 2026 but is not under active maintenance. \n\nShelfmark is a self-hosted web interface for searching and requesting books and audiobooks across multiple sources. Bring your own sources, metadata providers, and download clients to build a single hub for your digital library. Supports multiple users with a built-in request system, so you can share your instance with others and let them browse and request books on their own.\n\nWorks great alongside the following library tools, with support for automatic imports:\n- [Calibre](https:\u002F\u002Fcalibre-ebook.com\u002F)\n- [Calibre-Web](https:\u002F\u002Fgithub.com\u002Fjaneczku\u002Fcalibre-web)\n- [Calibre-Web-Automated](https:\u002F\u002Fgithub.com\u002Fcrocodilestick\u002FCalibre-Web-Automated)\n- [Grimmory](https:\u002F\u002Fgithub.com\u002Fgrimmory-tools\u002Fgrimmory)\n- [Audiobookshelf](https:\u002F\u002Fgithub.com\u002Fadvplyr\u002Faudiobookshelf)\n\n## ✨ Features\n\n- **One-Stop Interface** - A clean, modern UI to search, browse, and download from multiple configured sources in one place\n- **Multiple Sources** - Configurable web, torrent, usenet, and IRC source support\n- **Audiobook Support** - Full audiobook search and download with dedicated processing\n- **Flexible Search** - Search metadata providers (Hardcover, Open Library, Google Books) for rich book and audiobook discovery, or query configured sources directly\n- **Multi-User & Requests** - Share your instance with others, let users browse and request books, and manage approvals with configurable notifications\n- **Authentication** - Built-in login, OIDC single sign-on, proxy auth, and Calibre-Web database support\n- **Real-Time Progress** - Unified download queue with live status updates across all sources\n- **Network Flexibility** - Configurable proxy support, DNS settings, and optional Cloudflare handling for protected sources\n\n## 🖼️ Screenshots\n\n**Home screen**\n![Home screen](README_images\u002Fhomescreen.png 'Home screen')\n\n**Search results**\n![Search results](README_images\u002Fsearch-results.png 'Search results')\n\n**Multi-source downloads**\n![Multi-source downloads](README_images\u002Fmulti-source.png 'Multi-source downloads')\n\n**Download queue**\n![Download queue](README_images\u002Fdownloads.png 'Download queue')\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Docker & Docker Compose\n\n### Installation\n\n1. Download the [docker-compose file](compose\u002Fdocker-compose.yml):\n   ```bash\n   curl -O https:\u002F\u002Fraw.githubusercontent.com\u002Fcalibrain\u002Fshelfmark\u002Fmain\u002Fcompose\u002Fdocker-compose.yml\n   ```\n\n2. Start the service:\n   ```bash\n   docker compose up -d\n   ```\n\n3. Open `http:\u002F\u002Flocalhost:8084`\n\nOpen the web interface, then configure the sources and settings you want to use.\n\n### Volume Setup\n\n```yaml\nvolumes:\n  - \u002Fyour\u002Fconfig\u002Fpath:\u002Fconfig # Config, database, and artwork cache directory\n  - \u002Fyour\u002Fdownload\u002Fpath:\u002Fbooks # Downloaded books\n  - \u002Fclient\u002Fpath:\u002Fclient\u002Fpath # Optional: For Torrent\u002FUsenet downloads, match your client directory exactly.\n```\n\n> **Tip**: Point the download volume to your CWA or Grimmory ingest folder for automatic import.\n\n> **Note**: CIFS shares require `nobrl` mount option to avoid database lock errors.\n\n### Non-root container mode\n\n- Start the container as `1000:1000` with Docker `user: \"1000:1000\"` or `docker run --user 1000:1000`.\n- For Kubernetes, set `runAsUser: 1000`, `runAsGroup: 1000`, and `runAsNonRoot: true` together.\n- `PUID`\u002F`PGID` keep the default root startup flow.\n- Mounted paths must already be writable by `1000:1000`.\n- `USING_TOR=true` requires root startup.\n\n## ⚙️ Configuration\n\n### Search Modes\n\n**Direct**\n- Queries configured sources directly\n\n**Universal** (recommended)\n- Search via metadata providers (Hardcover, Open Library, Google Books) for richer results\n- Aggregates releases from multiple configured sources\n- Full audiobook support\n\n### Environment Variables\n\nEnvironment variables work for initial setup and Docker deployments. They serve as defaults that can be overridden in the web interface.\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `FLASK_PORT` | Web interface port | `8084` |\n| `INGEST_DIR` | Book download directory | `\u002Fbooks` |\n| `TZ` | Container timezone | `UTC` |\n| `PUID` \u002F `PGID` | Runtime user\u002Fgroup for the default root-startup flow (also supports legacy `UID`\u002F`GID`) | `1000` \u002F `1000` |\n| `SEARCH_MODE` | `direct` or `universal` | `universal` |\n| `USING_TOR` | Enable Tor routing (requires root startup) | `false` |\n\nSee the full [Environment Variables Reference](docs\u002Fenvironment-variables.md) for all available options.\n\nSome of the additional options available in Settings:\n- **Prowlarr** - Configure indexers and download clients to download books and audiobooks\n- **Additional audiobook sources** - Configure additional sources for audiobook discovery\n- **IRC** - Add details for IRC book sources and download directly from the UI\n- **Library Link** - Add a link to your Calibre-Web or Grimmory instance in the UI header\n- **File processing** - Customiseable download paths, file renaming and directory creation with template-based renaming\n- **Network Settings** - Custom proxy support (SOCKS5 + HTTP\u002FS) and configurable DNS\n- **Format & Language** - Filter downloads by preferred formats, languages and sorting order\n- **Metadata Providers** - Configure API keys for Hardcover, Open Library, etc.\n\n## 🐳 Docker Variants\n\n### Standard\n```bash\ndocker compose up -d\n```\n\nThe full-featured image with all network capabilities included.\n\n#### Tor Routing\nOptional Tor support for network privacy:\n```bash\ncurl -O https:\u002F\u002Fraw.githubusercontent.com\u002Fcalibrain\u002Fshelfmark\u002Fmain\u002Fcompose\u002Fdocker-compose.tor.yml\ndocker compose -f docker-compose.tor.yml up -d\n```\n\n**Notes:**\n- Requires root startup\n- Requires `NET_ADMIN` and `NET_RAW` capabilities\n- Timezone is auto-detected from Tor exit node\n- Custom DNS\u002Fproxy settings are ignored when Tor is active\n\n### Lite\nA lighter image without the built-in browser automation. Ideal for:\n\n- **External services** - Already running FlareSolverr or similar for other applications\n- **Alternative sources** - Using Prowlarr, IRC, or other configured sources\n- **Audiobooks** - Using Shelfmark primarily for audiobooks\n\n```bash\ncurl -O https:\u002F\u002Fraw.githubusercontent.com\u002Fcalibrain\u002Fshelfmark\u002Fmain\u002Fcompose\u002Fdocker-compose.lite.yml\ndocker compose -f docker-compose.lite.yml up -d\n```\n\nIf you need browser-based access with the Lite image, configure an external resolver in Settings.\n\n## 🔐 Authentication\n\nAuthentication is optional but recommended for shared or exposed instances. Multiple authentication methods are available in Settings:\n\n**1. Single Username\u002FPassword**\n\n**2. Proxy (Forward) Authentication**\n\nProxy auth trusts headers set by your reverse proxy (e.g. `X-Auth-User`). Ensure Shelfmark is not directly exposed, and configure your proxy to strip\u002Foverwrite these headers for all inbound requests.\n\n**3. OIDC (OpenID Connect)**\n\nIntegrate with your identity provider (Authelia, Authentik, Keycloak, etc.) for single sign-on. Supports PKCE flow, auto-discovery, group-based admin mapping, and auto-provisioning of new users.\n\n**4. Calibre-Web Database**\n\nIf you're running Calibre-Web, you can reuse its user database by mounting it:\n\n```yaml\nvolumes:\n  - \u002Fpath\u002Fto\u002Fcalibre-web\u002Fapp.db:\u002Fauth\u002Fapp.db:ro\n```\n\n### Multi-User Support\n\nWith any authentication method enabled, Shelfmark supports multi-user management with admin\u002Fuser roles. Users can have per-user settings for download destinations, email recipients, and notification preferences. Non-admin users only see their own downloads and can submit book requests for admin review. Admins can configure request policies per source to control whether users can download directly, must submit a request, or are blocked entirely.\n\n## Project Scope\n\nShelfmark is a manual search and download tool, the entry point to your book library, not a library manager. It finds books, downloads them, and sends them to a configured destination. That's the full scope.\n\nShelfmark intentionally does not:\n\n- **Track or manage your library** - it doesn't know or care what you already own\n- **Integrate with library software** - what happens after delivery is up to your library tool\n- **Monitor authors, series, or new releases** - there is no background automation\n- **Queue future downloads** - if a book isn't available now, Shelfmark won't watch for it\n\nThese are non-goals, not missing features.\n\n## Contributing\n\nShelfmark's core feature set is complete. Development focuses on stability, bug fixes, quality-of-life improvements, and refining the search experience. Contributions in these areas are welcome, please file issues or submit pull requests on GitHub.\n\nFeature requests that fall outside the project scope (library integration, automation, collection management) will be closed. If you're unsure whether something fits, open a discussion first.\n\n## Health Monitoring\n\nThe application exposes a health endpoint at `\u002Fapi\u002Fhealth` (no authentication required). Add a health check to your compose:\n\n```yaml\nhealthcheck:\n  test: [\"CMD\", \"curl\", \"-sf\", \"http:\u002F\u002Flocalhost:8084\u002Fapi\u002Fhealth\"]\n  interval: 30s\n  timeout: 30s\n  retries: 3\n```\n\n## Logging\n\nLogs are available via:\n- `docker logs \u003Ccontainer-name>`\n- `\u002Fvar\u002Flog\u002Fshelfmark\u002F` inside the container (when `ENABLE_LOGGING=true`)\n\nLog level is configurable via Settings or `LOG_LEVEL` environment variable.\n\n## Development\n\n```bash\n# Quality checks\nmake checks              # Run ALL static analysis (frontend + Python)\nmake python-checks       # Run Ruff, BasedPyright, and Vulture\nmake install-python-dev  # Sync Python runtime + dev tools with uv\n\n# Frontend development\nmake install     # Install dependencies\nmake dev         # Start Vite dev server (localhost:5173)\nmake build       # Production build\nmake frontend-typecheck  # TypeScript checks\n\n# Backend (Docker)\nmake up          # Start backend via docker-compose.dev.yml\nmake down        # Stop services\nmake refresh     # Rebuild and restart\nmake restart     # Restart container\n```\n\nThe frontend dev server proxies to the backend on port 8084.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## ⚠️ Disclaimer\n\nShelfmark is a search interface that displays results from external metadata providers and sources. It does not host, store, or distribute any content. The developers are not responsible for how the tool is used or what is accessed through it.\n\nUsers are solely responsible for:\n- Ensuring they have the legal right to download any material they access\n- Complying with copyright laws and intellectual property rights in their jurisdiction\n- Understanding and accepting the terms of any sources they configure\n\nUse of this tool is entirely at your own risk.\n\n## Support\n\nFor issues or questions, please [file an issue](https:\u002F\u002Fgithub.com\u002Fcalibrain\u002Fshelfmark\u002Fissues) on GitHub.\n","Shelfmark 是一个自托管的网页界面，用于跨多个来源搜索和请求电子书及有声书。它支持用户自定义来源、元数据提供者和下载客户端，构建统一的数字图书馆中心，并具备多用户请求系统，方便共享实例。核心功能包括一站式界面、多种来源配置（如网络、种子、Usenet 和 IRC）、有声书支持、灵活的搜索选项、多用户管理和请求、认证机制以及实时下载进度显示。适用于需要整合不同来源书籍资源并希望与他人共享的个人或团队使用。",2,"2026-06-11 03:41:25","high_star"]