bibliotecha-manual/docs/index.md

# 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 to setting up an offline-first local library for you 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 documetation] 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/
[Raspberry Pi 3 B+]: https://www.raspberrypi.org/products/raspberry-pi-3-model-b/
[Raspian Buster]: https://www.raspberrypi.org/documentation/raspbian/
[Etcher]: https://www.balena.io/etcher/
[official setup documentation]: https://www.raspberrypi.org/documentation/setup/

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

Once you've completed all the previous steps, it is 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.

[Manual installation]: #manual-installation

```bash
$ sudo -i
$ curl https://git.vvvvvvaria.org/varia/bibliotecha-install/raw/branch/master/bibliotecha.sh | bash
```

## Post-installation

After rebooting, there should be a Wifi hotspot available with the name
`Bibliotecha`. 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].

[http://bibliotecha.library]: http://bibliotecha.library

## Troubleshooting

* TODO

## Manual installation

* TODO