Join a library as a branch
A branch is a second Bookclerk install, on another computer, that joins a library to help with its work. The library is the Bookclerk everyone in a household signs in to.
A branch downloads books for its owner's store accounts on its own machine, and sends the results back to the library.
You might add a branch when:
- your books should download on your own computer rather than the shared server;
- the library runs on a small server, and a stronger computer should do the heavy work.
Note
A branch keeps its own database and its own operator. It never holds the library's database password or encryption keys.
- Install Bookclerk on the second computer and paste its operator token (steps 1 and 2 of Getting started).
- On the welcome screen, choose Join a library. On an install that is already set up, use Settings → Library → Join a library instead.
- Enter the library's address, for example
https://books.example.com. - If the library uses its own certificate, Bookclerk shows its fingerprint. Check that it matches the one on the library's Settings → Branches page, and confirm.
- Name the branch and choose Sign in. Your browser goes to the library.
- Sign in there as yourself. To have your store connections on the branch too, tick Bring my store connections to this branch (see Your store connections). Then choose Allow.
- You are back on the branch, which now says it is connected, and how many store connections it added.
If you cannot sign in to the library yourself, someone who can sends you an invite instead:
- They open Add a branch, in their menu or in Settings → User Management, and send you the invite.
- In step 3 above, you use the I have an invite tab.
An invite works once and expires, after a day by default.
Your store accounts can follow you to the branch, so you don't sign in to each store again there. On the library's Allow page, tick Bring my store connections to this branch. It is off unless you tick it.
- Only stores that let one sign-in be used in several places travel, such as Libro.fm, Chirp and GraphicAudio. The page lists which of yours will.
- A store that keeps one sign-in, such as Audible, stays on the library. Connect it on the branch yourself if you want it there.
- On the branch, the connections are added for its owner. An account someone else already connected there is left as it is.
- The branch's operator decides whether you may connect store accounts there at all. If they turned that off for you, nothing is added.
To add a connection to the library later, open Accounts on the branch and choose Add to library beside it. The library's operator rule applies there too. Adding later, and Revoke everywhere below, work only for the Owner who joined the library from the branch.
On the branch, Revoke here disconnects an account only on the branch. Revoke everywhere also disconnects it on every library you added it to, or brought it from. If a library can't be reached, the page says so; disconnect it there yourself. Disconnecting on the library doesn't reach the branch yet.
The library tells the branch which plugins it needs, such as the stores you use. Nothing runs on the branch until its operator approves each one in Settings → Library.
The same page shows what each plugin may reach, and lets you limit it.
A branch you joined as a Member receives only work for your own store accounts. A branch joined by an Administrator or Owner can receive any work from the library.
A library can ask your branch whether it can supply a book its people are looking at. Its people then see Available through your branch on that book in Discover and search.
Your branch answers with the books in its own library: always yours, and your members' books unless you turn off List my members' books for that library in Settings → Library. Each member can also keep their own books out with List my books to joined libraries in Settings → Account. With Share this branch's books off, your branch lists nothing to that library.
A change takes effect at your branch's next answer, so the library can show your branch as a source for up to two days afterwards.
The library sees the book and that your branch can supply it. It never sees whose account it's on. Nothing is copied until someone asks for it: someone on the library requests the book, and your branch sends it automatically while it still lists it.
The library's operator can also choose to receive all of your branch's listed books, not only yours. Your branch then also sends the books your members downloaded on it, under the same settings: nothing while Share this branch's books is off, no member's book while List my members' books is off, and nothing of a member who opted out. Your branch doesn't download anything extra for this.
Library shows Books in other libraries: every book in each library your server joined, as you would see it on that library's own Library page, merged into one list.
- Books on your own store accounts there are marked Yours, and Only yours shows just those.
- The same book in two libraries shows once, with both libraries named.
- The search box on Library narrows this list too.
- The list is refreshed when your server connects and every 30 minutes. If a refresh fails, the last list stays with a Try again button.
Settings → Library also has Keep copies on this computer for each library, on by default. With it on, when your server downloads one of your books and the library already has that book from the same store, your server copies the library's files instead of downloading from the store again. The copy is then converted and named by your own settings, like any other download. With it off, your server always downloads from the store. Your server runs the library's work and shows its books either way.
Note
If the library got its copy from a different store than yours, your server downloads the book from your store and keeps whichever of the two is the better recording. If the library keeps the book as several audio files, your server downloads the book from your store.
To see a library's books without joining it as a branch, sign in to it with a library card. Your server is then a clerk of that library: it shows the library's books, yours marked, and never takes its work.
- Open Settings → Library → Library cards and choose Sign in with a library card.
- Enter the library's address, the one you open it with in a browser, and choose Continue.
- If the library uses its own certificate, check that the fingerprint matches the one on the library's Settings → Branches page, and tick It matches.
- Name this computer. The library shows the name when it asks you to approve the card.
- Choose Sign in to library, sign in on the library with your account there, and approve the card.
The library sends you back to your server, which says Signed in to library. Within a minute, Library shows that library's books under Books in other libraries, yours marked, beside the books of any library your server is a branch of.
To stop, choose Sign out beside the library in the same list. Your server forgets the card and the books, and asks the library to end the card too. If the library can't be reached, end it later from your session list on the library. If the library ends the card first, the list says so and offers Remove; sign in again to get a new card.
While the card is signed in and the library is connected, your server can also use the library's copies of your books. When it downloads one of your books, it first asks the library for its copy and uses it the way a branch does with Keep copies on this computer on: a copy from the same store is used instead of downloading from the store again, and a copy from another store is used only when it is better than your own download. If no library answers with a usable copy, your server downloads from the store as usual. A card has no setting to turn this off.
The list also shows books the library doesn't have yet but one of its branches does, marked On a branch of library. Choose Request to ask the library to fetch one from its branch, as you could on the library itself. The request shows with your other requests there, and the book joins the library's list once the branch sends it.
A book on one of the library's store accounts that the library hasn't downloaded yet has a Request button too. Choose it to have the library download the book on that account; once the library has its copy, your server can use it like any other. If the library's administrator hasn't allowed you to request books, the button says so.
A server that is already a branch of a library shows your books there through that link, so it can't also hold a card for it.
A card only shows your books. A branch also downloads them with your store accounts and runs the library's work. You can switch either way without signing out first. Only the server's operator can switch, since only the operator joins or leaves a library.
To make a card a branch:
- In Settings → Library → Library cards, choose Make this server a branch beside the library.
- Approve the branch on the library, as for Join from a new install.
Your server joins with the card's address and certificate, under the card's name. Once the library approves, the card is signed out, and your books there come through the branch.
To keep only a card instead of a branch:
- In Settings → Library, choose Use a library card instead beside the library.
- Sign in on the library with your account there, and approve the card.
Once the library hands over the card, your server leaves the library as a branch, as Leave library does, and shows your books there through the card. If you don't approve the card, your server stays a branch.
Every install is a library of its own, with its own database, people and operator. What sets installs apart is whether other computers can reach them:
- A core branch has an address that other installs can connect to
(its
public_origin, see Configuration). Other branches can join it. - A local branch has no such address, such as a laptop or a computer at home. It connects out to the core branches it joins and never waits for anyone to connect to it.
When one install joins another, the relationship has a name too:
| Relationship | What it is |
|---|---|
| Local branch | A local branch contributing to a core branch. |
| Remote branch | A core branch contributing to another core branch. |
| Shared branch | Two installs sharing one database, so one library runs on more than one machine. See Shared branches. |
You can only join a core branch. A local branch and a remote branch work the same way and follow the same rules; the only difference is whether the branch that joins can be reached itself. A branch that gets an address later becomes a remote branch without joining again: each branch tells its library its address every few seconds, and Status and Settings → Nodes label it Remote branch or Local branch from that (see Remote and local branches).
A clerk is not a branch: it only shows a person their books (see Sign in with a library card).
On the branch, open Settings → Library → Leave library. To keep seeing your books there, choose Use a library card instead (see Switch between a card and a branch).
The library's operator or an Owner can also remove a branch from Settings → Nodes.
A branch can also share another install's database instead of keeping one of its own. It is then an extra copy of that library, so the library runs on more than one machine. Setting one up is an operator task; see Shared branches.
Source: docs/guide/branches.md at main · View as Markdown