# Bibliotecha Manual

> [Bibliotecha - Digital books need libraries too](https://bibliotecha.info/)

> Bibliotecha is a framework to facilitate the local distribution of digital
> publications within a small community. It relies on a microcomputer running
> open-source software to serve books over a local wifi hotspot. Using the
> browser to connect to the library one can retrieve or donate texts.
> Bibliotecha proposes an alternative model of distribution of digital texts
> that allows specific communities to form and share their own collections.

[TOC]

## Introduction

Welcome to the Bibliotecha manual! This guide serves as a human-friendly
document for setting up an offline-first local library for yourself and your
community.

## Prerequisites

Bibliotecha is made specifically for use on the cheap and widely accessible
[Raspberry Pi] single board computer and Debian based [Raspbian] operating
system.

You should follow the [official setup documentation] on the Raspberry Pi website
in order to get your board up and running. You will need it to have access to
the internet in order to download the necessary packages as well as access to
the command-line.

The current latest [Raspberry Pi 3 B+] model is recommended. This model is
chosen because it offers a built-in wireless card for convenient networking and
a sufficient memory allowance of 1GB. It is possible to use other models of
board but they should at least provide these guarantees.

[Raspbian Buster] is the current latest recommended version of the standard
Raspberry Pi operating system. [Etcher] is a useful and simple tool for
flashing the operationg system onto the SD card which you will plug into your
Raspberry Pi.

[Raspberry Pi]: https://www.raspberrypi.org/
[official setup documentation]: https://www.raspberrypi.org/documentation/setup/
[Raspberry Pi 3 B+]: https://www.raspberrypi.org/products/raspberry-pi-3-model-b/
[Raspbian]: https://www.raspberrypi.org/documentation/raspbian/
[Raspbian Buster]: https://www.raspberrypi.org/blog/buster-the-new-version-of-raspbian/
[Etcher]: https://www.balena.io/etcher/

## Pre-installation

Before getting started, we need to perform some preparatory steps. These steps
must be completed successfully before moving on with the rest of the guide.

You should run the following commands at the command-line interface of your
Raspberry Pi.

Firstly, we switch our user to the root account:

```bash
$ sudo -i
```

We then perform the initial system update and upgrade:

```bash
$ apt update
$ apt upgrade
```

We should then perform a number of steps within the [raspi-config] tool:

```bash
$ raspi-config
```

* Change the user password
    * Choose the ``Change User Password`` option.
    * It is important to configure your Raspberry Pi with a secure passphrase.
      A [diceware passphrase] is a recommended approach for choosing a
      sufficiently strong passphrase.

* Choose a hostname
    * Follow the ``Network Options > Hostname`` options.
    * The hostname will be the name that identifies the Raspberry Pi
      on the local network.

* Configure predictable network interfaces
    * Follow the ``Network Options > Network interface names`` options.
    * It is important to enable predictable network interface names
      so that the automatic installation script can detect which network
      interfaces are in use.

* Configure the localisation
    * Follow the ``Localisation Options > Change Locale`` options.
    * It is recommended to ensure that the ``en_GB.UTF-8 UTF-8`` locale
      is selected. This is the default. Once this is selected, select ``<Ok>`` on the
      two following dialogs to generate the locale.

* Expand the SD card partition
    * Follow the ``Advanced Options > Expand filesystem`` options.
    * This allows more space on the SD card to be used. This is important
      for when you will start to place more and more digital books in your
      Bibliotecha.

The Raspi-config interface then ask you to restart the Raspberry Pi which you
should do. If not, you can also run this from the command-line:

```bash
$ reboot
```

Remember, you will need to use your new user passphrase to access the Raspberry
Pi after rebooting it. Make sure you store this passphrase somewhere safe!

[raspi-config]: https://www.raspberrypi.org/documentation/configuration/raspi-config.md
[diceware passphrase]: https://www.rempe.us/diceware/#eff

## Automated installation

It is now time to run the automatic installation. This script will install and
configure all the necessary moving parts of Bibliotecha.

If you're interested in doing this process manually (for the purpose of
learning, for example), a [Manual installation] guide is provided.

If you would first like to read the script, the [source is available].

On the Raspberry Pi once again, run the following commands:

```bash
$ sudo -i
$ curl https://install.bibliotecha.info | bash
```

The script will automatically reboot your Raspberry Pi when it is finished.

If you run into any issues, please see the [Troubleshooting section].

[Manual installation]: #manual-installation
[Troubleshooting section]: #troubleshooting
[source is available]: https://git.vvvvvvaria.org/varia/bibliotecha-install/src/branch/master/bibliotecha.sh

## Post-installation

After rebooting, there should be a Wifi hotspot available with the name
`Bibliotecha`. You should wait a few minutes for this hotspot to become
available. This Wifi access point is being served from the Raspberry Pi.  You
should be able to connect to this Wifi. It is not password protected.

Once connected you should be directed to the so-called "captive protal" of the
Bibliotecha where it explains how to enter the library and use it. The library
should be available at [http://bibliotecha.library].

You will be required to configure the [Calibre-web] installation. Extended
configuration documentation is available from the [Calibre-web wiki]. The most
important part is the "Location of Calibre database" for which you can enter
the following path:

> /opt/calibre-database

This is the default installation path used by the installation script.

You may also want to look at the "Feature Configuration" section where you can
decide whether to allow uploading, anonymouse browsing and allowing public
registrations. These depend on your context and for who you will serve the
library to.

Click "Submit", "Login" and you will be redirected to the library login page.
The default adminstration password login details are:

> Username: admin
>
> Password: admin123

You should change these details to secure your adminstration account.

[http://bibliotecha.library]: http://bibliotecha.library
[Calibre-web]: https://github.com/janeczku/calibre-web/
[Calibre-web wiki]: https://github.com/janeczku/calibre-web/wiki/Configuration

## Maintaining a Community Library

Once your Bibliotecha is configured you can start to think about how you and
your community would like to maintain the library. You should ask yourself some
questions:

  * Who will be the digital librarians? The catalogue will need care.
  * Will you allow public registrations? Will you allow public uploads?
  * How will you publicise the library within the local context?
  * What kind of library do you want to create? What are the themes?
  * Who will be responsible for maintaing the system?

## Understanding Bibliotecha Networking

Bibliotecha uses standard, venerable and stable GNU/Linux networking tools and
configuration to enable the [local-first] networking setup. Installing, running
and maintaining a network configuration is no easy topic! However, it is a
useful skill to have. Overall, Bibliotecha is made up of the following programs
and configurations:

  * [/etc/network/interfaces.d/](https://manpages.debian.org/buster/ifupdown/interfaces.5.en.html): The network interface configuration
  * [/etc/hosts](https://manpages.debian.org/buster/manpages/hosts.5.en.html): The hostname definitions
  * [Hostap](https://wiki.debian.org/hostap): The Wifi access point provider
  * [Dnsmasq](https://wiki.debian.org/HowTo/dnsmasq): The DNS and DHCP server
  * [Dhcpcd](https://manpages.debian.org/buster/dhcpcd5/dhcpcd.8.en.html): The DHCP client
  * [Calibre](https://calibre-ebook.com/): The library database
  * [Calibre-web](https://github.com/janeczku/calibre-web/): The library web application
  * [Lighttpd](https://www.lighttpd.net/): The web server

When your Bibliotecha is setup and running, it is doing a number of things. It
is first serving a Wireless access point (Hostap) which your devices can
connect to. After you connect, your device is given an IP address on the local
network (Dnsmasq and Dhcpcd) as well as a local DNS entry (mydevice.library,
for example). Once you open a web browser, it will indicate that you need to
log into the network but in fact, you are brought to a web page (Lighttpd)
which shows you how to reach the library web application (Calibre-web).

[local-first]: https://www.inkandswitch.com/local-first.html

## Troubleshooting

Because Bibliotecha is made up of a number of moving parts it is not feasible
for this manual to cover all the possible issues. However, we try our best here
to provide context, background, useful tips and tricks to help you become
familiar with fixing your Bibliotecha. We recommend a DIWO (Do It With Others)
approach!

Please make sure to take some time to read [Understanding Bibliotecha
Networking] so that you are familiar with all the moving pieces. When
troubleshooting, it is important to narrow down which piece of the puzzle is
responsible. To do this, you need to know what the pieces are.

If all else fails, please send an email to the public [mailing list].

### The automatic installation script failed

#### I cannot connect to the internet from the Raspberry Pi
#### The wireless access point is not available
#### I do not receive an IP address when I connect
#### Bibliotecha.library is unavailable
#### How to upgrade Calibre-web

[Understanding Bibliotecha Networking]: #understanding-bibliotecha-networking
[mailing list]: https://we.lurk.org/postorius/lists/bibliotecha.we.lurk.org/

## Manual installation

It is possible to install Bibliotecha manually. This can be useful and fun if
you would like to learn more about GNU/Linux networking tools and interfaces.
These skills are generally useful but especially so when considering community
networks.

The following guide follows the steps of the automatic installation script.

### Update the System
### Install Networking Packages
### Configure Network Interfaces
### Configure Dnsmasq
### Configure Hostapd
### Configure the Hosts file
### Enable Networking Services
### Install and Configure Lighttpd
### Install and Configure Calibre
### Install and Configure Calibre-web
### Setup a new MOTD