Taking another run at the manual once more
This commit is contained in:
parent
80795d64c9
commit
4d0d74b08e
147
docs/index.md
147
docs/index.md
@ -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/
|
||||
[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/
|
||||
[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.
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user