HUB
Sign inSign up

derkezorm/nexbooks

By derkezorm

•Updated 1 day ago

Your e-books and audiobooks on your own server: read and listen in the browser.

Image
0

361

derkezorm/nexbooks repository overview

⁠nexbooks

Your e-books and audiobooks, on your own server. A library to read in and listen to in the browser, with one book holding all its editions: the e-book and the audiobook of the same work sit side by side, each with its own place (they may be different editions, a shortened recording, another translation), so nothing is carried over between them. One container, SQLite, and your books stay plain files in your folders.

The shelf: a section of spines for each genre

Early days. This is the first release. It does what is written below, and it has been tried on invented libraries in Chromium, Firefox and the WebKit of the tests; Safari on a Mac, an iPhone or an iPad has not been tried yet. Expect rough edges, keep a backup, and open an issue when something is wrong. Do not rely on it yet.

nexbooks manages, reads and plays books, and can fetch them. It reads the folders you point it at and changes nothing in them, unless you turn on tidying (Settings, Tidying): renaming and moving by a scheme, after a preview and your confirmation, never overwriting anything, with a way back. Books also come into a library by what you upload and by what fetching files there (below, "Settings, Acquisition"). In those two cases, and when tidying is on, a file that lies twice in one book, byte for byte, goes to the library's trash; in every other library nothing is touched, and such copies are only named. A book can be moved into another library you look after (its page, "Move to another library"), with its place, bookmarks and history kept.

Notes on use. nexbooks comes with no indexers and no sources of books. The operator enters them (Settings, Acquisition) and is responsible for loading only content they may use. nexbooks never gets around a copy protection: protected books are recognised and turned down. A few things are off until the operator turns them on: seeding of torrents, and Audible.

  • A shelf of spines. Every genre is a shelf; a spine is as wide as the book is thick and has the colour of its cover. Pressing it turns the book to its cover and opens its page in the colours of the book. Covers and a sortable list are one switch away, and so is an overview of the authors with their photos.
  • One book, several editions. EPUB, AZW3 and MOBI of one book are one edition; the e-book and the audiobook are twins of one work, each with its own place. A translation or an abridged recording is another edition of the same book.
  • Reading and listening in the browser. An e-book reader (EPUB, MOBI, AZW3, PDF) and a player for audiobooks with chapters, speed, a sleep timer and the lock screen. The place is kept on the server, for every person on their own.
  • Discover. Best sellers, new and coming books for several countries, what is read now, and the gaps in the series you read, with a wish list. What you already have is hidden.
  • The reading stack. A tower of books for every year, each as thick as it is on the shelf, with a look back.
  • Mine to keep. The books are not in nexbooks's data folder and not in its backup: they lie where you keep them, as files, and belong in the backup your server makes anyway.
  • Several people. Each person has their own progress, shelf and lists. The operator decides who sees which library, and the operator does not see what the others read or listen to.
  • Best kept at home. nexbooks is meant for your own network; from on the way, reach it through a VPN. It comes with a second factor from the start, passkeys, sign-in through your own provider and a checklist in the settings. Everything the web app does goes through an open API (/api/v1) for your own tools.
The page of a book: e-book and audiobook side by sideListening, in the colours of the book
ReadingBrowse, the first tab of Discover: shelves by topic
The reading stackThe shelf on a phone

nexbooks is one of the nex apps and looks like them: warm paper by day, a dark reading room by night, Bordeaux as its colour. The pictures show an invented library: none of these books exists.

⁠Start

services:
  nexbooks:
    image: ghcr.io/derkezorm/nexbooks:latest
    container_name: nexbooks
    restart: unless-stopped
    ports:
      - "127.0.0.1:8580:8000"
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp:size=256m,mode=1777
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_READ_SEARCH
      - SETUID
      - SETGID
    volumes:
      - ./data:/data
      # Your books, read-only: nexbooks writes into them only if you turn on tidying (then drop the ":ro").
      # Make a library of the folder in Settings, Libraries.
      - /path/to/your/books:/books:ro
    environment:
      PUID: 1000
      PGID: 1000
      TZ: Europe/Berlin
docker compose up -d

The container may not gain rights later and keeps only what its start needs: setting the owner of /data (CHOWN, DAC_READ_SEARCH) and dropping from root to the user nexbooks (SETUID, SETGID). nexbooks itself runs as that user, with none.

Built from source instead: clone this repository, use docker-compose.yml as it is (it has build: .) and run docker compose up -d --build. The file has every option explained.

Open http://127.0.0.1:8580 on that machine (the port listens only there; the comment in docker-compose.yml⁠ says how to change that). The first account you create there is the operator. It needs the setup code from the log, so that nobody who reaches a fresh instance first can take it:

docker logs nexbooks

shows the code, new at every start until nexbooks is set up. To choose it yourself, set NEXBOOKS_SETUP_TOKEN. Right after the password the account sets up its second factor; then the operator invites the others by link. Everything personal is under "My account" for everybody; "Settings" is the operator's and holds the server.

⁠Libraries and the scan

A library is a folder of books that the operator makes known (Settings, Libraries): a name, a folder below /books, and what it holds (e-books, audiobooks or both). Mount your books read-only at /books (see the compose file above); the operator may only choose folders at or below NEXBOOKS_LIBRARY_ROOTS, never the data folder and never a folder that overlaps another library. The operator decides who sees which library (read; acquire to also ask for books to be fetched; manage to also start a scan); a person sees the books of their libraries and of no other, the operator included.

Settings, Acquisition (the operator's) is where nexbooks is told where books come from: indexers (Newznab and Torznab, each tested before it is saved, with the book categories it lists chosen for your language), a Prowlarr whose indexers it takes over and keeps in step, and download programs (SABnzbd, NZBGet, qBittorrent, Transmission, Deluge; nexbooks makes its own category nexbooks in them and reads it back). Also the formats (a ranking per kind with a tick for each, PDF off from the start), the languages, the library the books go into (with a check that nexbooks may write there), the naming and the settings of the automatic work. Who may acquire in a library opens "See releases" on the page of a book (a missing e-book or recording, a better format than the one there is) or of a book of the sources: every indexer is asked at once, each release is judged (author, title, volume, language, format, abridged or a play, bundle, sample) with the reasons as words, the best one by your ranking comes first, and one click hands it to the download program. Wishes: Acquire on a book asks for it, as an e-book, a recording or both, in a language and for a library; nexbooks searches at once and (with the main switch on) loads the best release that passes. The page Acquire shows what is wished, what runs (progress, time left, the seed goal), what needs you (a folder it cannot find with a suggestion to confirm, a library it may not write in, a job it lost, a question of the check) and what became of everything, and the blocklist. A book that was fetched and is not the one wished: "Wrong book" on its page (Edit) sends it away. The files go into the trash of the library, the release is blocked, the history keeps a line, and a new wish looks for another release. What people had in the book (place, bookmarks, finished passes) is kept with the files and comes back when you take them out of the trash. The automatic work: with the main switch on, wishes that found nothing are searched again in the time you chose (1 to 24 hours, one wish at a time, the one that waited longest first), the newest entries of every indexer are read (every 5 to 60 minutes) and held against the wishes, a book that is not out waits for its day, an indexer that reached its limit of the day (midnight of your time zone) keeps its wishes waiting while the others go on, a failed download is replaced at once by the next release, and a book below the goal of your ranking is looked for in a better format. A wish has at most the number of downloads you chose in 24 hours; one that found nothing for a week is looked for once a day, after a month once a week; what nexbooks does by itself uses at most 70 percent of an indexer's limit of the day, the rest is for new wishes and "Search now". Settings, Acquisition, Automation shows when it last ran and comes back next and what it did (numbers only). Checking and filing: a finished download is read by the same readers as the scan (the language in the EPUB, title, author, series, a recording's tags and running time) and held against the wish; what passes goes into the library by your naming scheme (a torrent linked, so that it can go on seeding if you choose to seed; a Usenet download moved; else copied; never over a file), joins the work it was wished for, and the wish is done. A release in another language, another volume, a format you did not tick, a program or script in it, or an archive that is not safe to unpack is blocked and the next one is looked for; nothing of it goes into a library. A recording whose running time fits an abridged version, a bundle that does not say which volume is which, or files that name another title wait for you under "Needs you". A better format replaces a worse one (the old one goes into a hidden trash in the library for 30 days, Settings, Acquisition, Formats); a place in an e-book is carried over by its share and the reader is told. Upload: "Upload" in the library and on a missing form of a book takes the files of a book from a computer or a phone (EPUB, PDF, AZW3, MOBI, M4B, MP3, M4A, FLAC; an audiobook as several files or a ZIP) and files them the same way. It needs the right acquire and a library nexbooks may write in. Seeding is off from the start: a torrent leaves its program once the book is filed. Settings, Acquisition, Automation lets you choose a ratio of 1.0 or seven days instead; with "not at all" the torrent goes even when the tracker asks for a ratio or a minimum time, which private trackers often do. A choice made in an earlier version stays. Keys and passwords are sealed and never shown again, and every request goes to the address you typed and to no other host.

nexbooks reads the folder in the background (once an hour unless set otherwise, and on "Scan now") and recognises what it finds, without touching a file:

  • E-books: EPUB (title, authors, language, ISBN, series, cover, table of contents), PDF (title, author, pages), AZW3 and MOBI (the header). Audiobooks: M4B, M4A, MP3, FLAC, Ogg and Opus (tags, running time to the second (an MP3 that does not say its length has its frames counted), chapters, cover). Files beside a book are read as well: metadata.json (Audiobookshelf), metadata.opf (Calibre), cover.jpg and folder.jpg. What a file says about itself wins over a file beside it, and that over its name.
  • One book, several forms. The same book as EPUB, AZW3 and MOBI is one edition with three files (all stay where they are); the parts of an audiobook, also in Audio, MP3, CD 1 and CD 2 folders under the folder of the book, are one edition (the number in a name like Title-1v6 is the part, never the title); a folder of a series with a numbered folder for each book (1 - Title, 2 - Title) is one book for each; the e-book and the audiobook of the same work are twins of one work. Volume 2 of a series is never volume 3, and an author is never matched by the last name alone. ß and ss, ä and ae are the same letters in a title and in a name. A pen name and a real name are one author only on proof (the other names Hardcover knows, or the same ISBN or ASIN), never by a guess; the page of a book then shows the real name with the pen name beside it ("as ...").
  • Only what changed is read again. A file changed in the last minute waits for the next run. Links are never followed (they are listed under the library's problems), a folder that is gone, or holds no book while nexbooks knows books in it (a stray file of an unmounted share does not count as a book), stops the run instead of marking everything missing; a walk of more than 500,000 entries marks nothing missing for what it did not see. A file that cannot be read, a name that is no valid text (bytes that are no UTF-8) and a fault while one book is put together go on the list of problems and do not stop the rest; only a fault of the database or the folder ends a run. Files that are gone are marked, never deleted.
  • A book in two libraries is seen as the libraries of the person show it. If the e-book lies in one library and the audiobook in another, a member of only the second reads, off the book, what the audiobook says (its description, series, genre, pages, authors, cover, when it came) and nothing the first copy says.
  • The pages of an EPUB are an estimate (an EPUB has none): the amount of text divided by what a printed page holds. A PDF is counted.

Removing a library takes it out of nexbooks; the files stay where they are.

⁠Matching with sources

nexbooks can ask sources on the internet about the books it found, to fill in what the files leave empty: the series and the place in it, the description, the genre, the year, the cover, the narrators, and, for a recording, which recording it is (the unabridged reading, an abridged one or a play, proven by its running time within 5 percent, which needs Audible). No source is required and none belongs to the project. Settings, Sources has a main switch and one per source:

SourceFrom the start
Open LibraryonNothing to set up.
Audible's catalogue (a market at a time)offThe operator is asked once, when setting up acquisition or opening the sources, and chooses "Use Audible" or "Without Audible" (Settings, Sources changes it later). An unofficial interface: nexbooks only reads, slowly, and keeps what it read for a day. What Audible brings: the running time of a recording, which proves the version (the unabridged reading, a shortened one or a play) and so keeps wrong and shortened recordings out, and the audiobook lists of Discover (new and coming). Without it everything else goes on; a downloaded recording that nothing proves is not filed as the unabridged one on a guess, a person decides (under "Needs you").
Hardcovernot connectedA read-only token of your own (hardcover.app/account/api), pasted into Settings, Sources. Its sign-in by device code is not built in.
German National LibraryonFor German titles only: the author, the year of the first edition, the ISBN, the series and the subject group the genre comes from.
The national libraries of France, Sweden, the Netherlands and NorwayonNothing to set up. Only the page of an author asks them, for the titles of their language.
Apple Books ChartsonNothing to set up. Only Discover reads it: the best-selling e-books of a country, and of each genre for the shelves of Browse.
Wikidata and Wikimedia CommonsonNothing to set up. Only the photos and short biographies of authors come from it: a photo only when the author is certain (a book of yours is among their works) and only under a free licence, shown with its photographer and licence. No other source gives a photo. A photo called author.jpg in an author's folder is always read. One switch (Settings, Sources) turns the look-up of authors off.
  • What goes out is a title, an author and an ISBN. Never a file, a folder name or the name of a library.
  • Slowly, and once: every source is asked at its own pace (Hardcover: 60 a minute, 5,000 a day), what comes back is kept for a month (a miss for a day; what Audible and Apple say, a day), and a source that fails rests for a while. With the main switch off nothing is asked and everything the files give stays as it is.
  • Which sources, by language (Audible when it is on): a German book is asked at the German National Library and Audible (Open Library only when those do not settle it), an English one at Open Library, Audible and Hardcover, any other at Audible, Open Library and Hardcover. The genre is the majority of the voices of the file and the sources, and a book none of them classes gets the genre of most of the other books of its author in the same library, marked as a guess.
  • Three answers: sure (applied by itself), maybe and open. The books that need a look are in a list for the people who look after the library (a member with manage), with the proposals side by side and the reason for each. A person can take a proposal, search for another, or leave the book as it is; what a person decided is never changed by a later run. To decide, a person can look into the book: the first pages of an e-book in the reader's own frame, a short listen into a recording (the start, a third in, the middle, the chapters), and what the file says (its name and folder, title, author, narrator, ISBN, publisher, year, language, running time, chapters, pages, the picture inside it) beside each proposal, with what the file contradicts told apart from what it says nothing about. Nothing of it saves a place or a bookmark.
  • The rank: a person, then the file, then a source. A source never replaces what the file says and never writes to it; files are never changed.
  • A book in two libraries (an e-book here, its translation there) is one work for the sources and for the server, and each member still sees only the editions of their libraries and what those say.

The full README is on GitHub: https://github.com/DerKezorm/nexbooks#readme⁠

Tag summary

Content type

Image

Digest

sha256:09bb2afdc…

Size

94.6 MB

Last updated

1 day ago

docker pull derkezorm/nexbooks