# 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.

## Join from a new install

1. Install Bookclerk on the second computer and paste its operator token
   (steps 1 and 2 of [Getting started](/docs/guide/getting-started/index.md)).
2. On the welcome screen, choose **Join a library**. On an install that is
   already set up, use **Settings → Library → Join a library** instead.
3. Enter the library's address, for example `https://books.example.com`.
4. 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.
5. Name the branch and choose **Sign in**. Your browser goes to the
   library.
6. 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](#your-store-connections)). Then choose
   **Allow**.
7. You are back on the branch, which now says it is connected, and how
   many store connections it added.

### Join with an invite

If you cannot sign in to the library yourself, someone who can sends you an
invite instead:

1. They open **Add a branch**, in their menu or in **Settings → User
   Management**, and send you the invite.
2. 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 connections

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.

## Approve the library's plugins

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.

## What the library can ask of a branch

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.

## What the library can see of your books

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](/docs/guide/discover/index.md#available-through-a-branch).

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.

## See the books of the libraries you joined

**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.

## Sign in with a library card

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.

1. Open **Settings → Library → Library cards** and choose **Sign in with a
   library card**.
2. Enter the library's address, the one you open it with in a browser,
   and choose **Continue**.
3. 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**.
4. Name this computer. The library shows the name when it asks you to
   approve the card.
5. 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.

### Switch between a card and a branch

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:

1. In **Settings → Library → Library cards**, choose **Make this server a
   branch** beside the library.
2. Approve the branch on the library, as for
   [Join from a new install](#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:

1. In **Settings → Library**, choose **Use a library card instead** beside
   the library.
2. 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.

## Core and local branches

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](/docs/server/configuration/index.md)).
  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](#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](/docs/server/branches/index.md#remote-and-local-branches)).

A **clerk** is not a branch: it only shows a person their books (see
[Sign in with a library card](#sign-in-with-a-library-card)).

## Leave a library

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](#switch-between-a-card-and-a-branch)).

The library's operator or an Owner can also remove a branch from
**Settings → Nodes**.

## Shared branches

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](/docs/server/branches/index.md#shared-branches).
