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