|
|
|
@ -9,16 +9,12 @@ |
|
|
|
> 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 |
|
|
|
document for setting up an offline-first local library for yourself and your |
|
|
|
community. |
|
|
|
|
|
|
|
## Prerequisites |
|
|
|
@ -27,7 +23,7 @@ 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 |
|
|
|
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. |
|
|
|
@ -43,15 +39,17 @@ 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/ |
|
|
|
[Raspian Buster]: https://www.raspberrypi.org/documentation/raspbian/ |
|
|
|
[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/ |
|
|
|
[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. |
|
|
|
|
|
|
|
@ -118,36 +116,149 @@ Pi after rebooting it. Make sure you store this passphrase somewhere safe! |
|
|
|
|
|
|
|
## 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. |
|
|
|
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. |
|
|
|
|
|
|
|
[Manual installation]: #manual-installation |
|
|
|
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://git.vvvvvvaria.org/varia/bibliotecha-install/raw/branch/master/bibliotecha.sh | bash |
|
|
|
$ 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`. 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. |
|
|
|
`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 |
|
|
|
|
|
|
|
* TODO |
|
|
|
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 |
|
|
|
|
|
|
|
* TODO |
|
|
|
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 |
|
|
|
|
