Write the manual guide

This commit is contained in:
Luke Murphy 2019-07-09 15:13:11 +02:00
parent 4d0d74b08e
commit 8e6c03088f
No known key found for this signature in database
GPG Key ID: 5E2EF5A63E3718CC

View File

@ -231,14 +231,75 @@ 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]. If all else fails, please send an email to the public [mailing list].
### The automatic installation script failed All of the following commands should be run as the root user.
#### I cannot connect to the internet from the Raspberry Pi #### I cannot connect to the internet from the Raspberry Pi
If you are connecting an Ethernet cable to your Bibliotecha in order to connect
it to your local router and have access to the internet, then you might notice
that the requests do reach their destination.
Bibliotecha is configured to capture all the network requests it receives and
point them to the library interface. You will need to temporarily disable the
`dnsmasq` service:
```bash
$ systemctl stop dnsmasq
```
It should then be possible to connect to the wider internet now.
#### The wireless access point is not available #### The wireless access point is not available
The access point is responsibility of the `hostapd` program. You should check
the status of the running service with:
```bash
$ systemctl status hostapd
```
If there are errors, you can see the logs with:
```bash
$ journalctl -u hostapd
```
You may also attempt to restart this service afterwards:
```bash
$ systemctl restart hostapd
```
You may also want to inspect the `/etc/hostapd/hostapd.conf` configuration.
#### I do not receive an IP address when I connect #### I do not receive an IP address when I connect
#### Bibliotecha.library is unavailable
Providing IP addresses is the responsibility of the `dnsmasq` and `dhcpcd`
service. You should check the status of `dnsmasq` with:
```bash
$ systemctl status dnsmasq
```
You should make sure that `dhcpcd` is running with:
```
$ dhcpcd5
```
#### How to upgrade Calibre-web #### How to upgrade Calibre-web
You'll need to re-connect your Bibliotecha to the internet with an ethernet
cable and then run the following commands:
```bash
$ systemctl stop cps
$ cd /var/www/calibre-web
$ git pull origin master
$ .venv/bin/pip install -r requirements.txt
$ systemctl start cps
```
[Understanding Bibliotecha Networking]: #understanding-bibliotecha-networking [Understanding Bibliotecha Networking]: #understanding-bibliotecha-networking
[mailing list]: https://we.lurk.org/postorius/lists/bibliotecha.we.lurk.org/ [mailing list]: https://we.lurk.org/postorius/lists/bibliotecha.we.lurk.org/
@ -251,14 +312,288 @@ networks.
The following guide follows the steps of the automatic installation script. The following guide follows the steps of the automatic installation script.
### Changing to Root
All commands should be run as the root user.
Change the user to the root user with:
```bash
$ sudo -i
```
### Update the System ### Update the System
We should update the system before going further:
```bash
$ apt update
```
This makes sure that we have the latest package listing from the online Debian
package list.
### Install Networking Packages ### Install Networking Packages
We then need to install the networking packages that we will need:
```bash
$ apt install -y \
dhcpcd \
dnsmasq \
dnsutils \
hostapd \
wireless-tools
```
Afterwards, we'll make sure to stop these services running while we work on the
installation right now. We can do that with:
```bash
$ systemctl stop dnsmasq
$ systemctl stop hostapd
```
We do want these services to be enabled when we reboot though:
```bash
$ systemctl unmask hostapd
$ systemctl enable hostapd
$ systemctl enable dnsmasq
```
We'll also want to disable and stop the `avahi-daemon` which we won't be using
since we rely on `dnsmasq` to handle our DNS configuration and serving:
```bash
$ systemctl stop avahi-daemon
$ systemctl disable avahi-daemon
```
### Configure Network Interfaces ### Configure Network Interfaces
We now need to configure our network interfaces. The network interfaces
correspond to the Ethernet port and the Wireless card. These are how the
Raspberry Pi connect to other devices for networking uses.
We need to learn the names of our network interfaces:
```bash
$ ip a
```
The ethernet interface is the name beginning with "en" and the wireless
interface is the one beginning with "wl". These are the predictable inteface
naming conventions which we rely on.
For the following steps, I assume the following:
* Ethernet: enx78e7d1ea46da
* Wireless: wlp2s0
We then configure the ethernet interface. We put the following in
`/etc/network/interfaces.d/enx78e7d1ea46da`:
```bash
auto eth0
allow-hotplug enx78e7d1ea46da
iface enx78e7d1ea46da inet dhcp
```
This configuration allows the default behaviour for the Ethernet interface.
When you plug in an ethernet cable, typically coming from your local network
router, you will receive a dynamic IP from that router. This makes it easy to
reach the internet later.
We then configure the wireless interface. We put the following in
`/etc/network/interfaces.d/wlp2s0`:
```
auto wlp2s0
iface wlp2s0 inet static
address 10.0.0.1
netmask 255.255.255.0
```
This configuration sets up a static IP address for the wireless interface. We
do this so as to put the IP address within the range of the addresses which we
allow in the local network. We will configure this range in the following step.
### Configure Dnsmasq ### Configure Dnsmasq
In the `/etc/dnsmasq.d/wlp2s0.conf` file, we put the following:
```bash
bogus-priv
server=/library/10.0.0.1
local=/library/
address=/#/10.0.0.1
interface=wlp2s0
domain=library
dhcp-range=10.0.0.50,10.0.0.200,255.255.255.0,12h
dhcp-option=3,10.0.0.1
dhcp-option=6,10.0.0.1
dhcp-authoritative
```
This configuration sets up a local `.library` domain and a range of IP
addresses that can be assigned in the `10.0.0.50` - `10.0.0.200` range. It
also makes sure to resolve all unknown domain requests to the `10.0.0.1` IP.
This is useful for the purposes of the captive portal configuration later on.
### Configure Hostapd ### Configure Hostapd
We need to set up the wireless access point too. In the
`/etc/hostapd/hostapd.conf` we add:
```bash
interface=wlp2s0
ssid=Bibliotecha
hw_mode=g
channel=11
auth_algs=1
```
We also need to make sure that `hostapd` uses this configuration. We have to
ensure that the following is uncommented and present in the
`/etc/default/hostapd` file:
```bash
DAEMON_CONF="/etc/hostapd/hostapd.conf"
```
### Configure the Hosts file ### Configure the Hosts file
### Enable Networking Services
We need to register the library on the network. In the `/etc/hosts` file we put
the following at the end of the file after all the other entries:
```bash
10.0.0.1 bibliotecha.library
```
### Install and Configure Lighttpd ### Install and Configure Lighttpd
Moving on, we should install the web server which will respond to network
requests and return the web pages of the library interface. We can install
Lighttpd with:
```bash
$ apt install -y lighttpd
```
When then need to make sure that the following configuration is available in
the `/etc/lighttpd/lighttpd.conf` file:
```bash
server.document-root = "/var/www"
server.modules += ("mod_proxy",)
include "bibliotecha/bibliotecha.conf"
```
When then create the Bibliotecha configuration with:
```bash
$ mkdir /etc/lighttpd/bibliotecha
```
And then make sure the following is in the
`/etc/lighttpd/bibliotecha/bibliotecha.conf` file:
```bash
server.error-handler-404 = "/bibliotecha/index.html"
$HTTP["host"] == "bibliotecha.library" {
proxy.server = ("" => (("host" => "127.0.0.1", "port" => "8083")))'
}
```
This ensures that all unknown requests are pointed to the captive portal page
of Bibliotecha. And when we request the `http://bibliotecha.library` domain, we
are then pointed to the Calibre-web installation.
### Install and Configure Calibre ### Install and Configure Calibre
Calibre is responsible for maintaining the underyling database of the library. We
can install it with:
```bash
$ apt install -y calibre
```
This will take some time as there are man required packages. Once it if
finished, you will then need to create a new database for the Calibre-web
installation to use.
We should run the following:
```bash
$ mkdir /opt/calibre-database
$ /usr/bin/calibredb restore_database --really-do-it /opt/calibre-database
```
### Install and Configure Calibre-web ### Install and Configure Calibre-web
We now setup the Calibre-web installation. We first get a copy of the source with:
```bash
$ mkdir /var/www/calibre-web
$ git clone https://github.com/janeczku/calibre-web /var/ww/calibre-web
$ cd /var/www/calibre-web
```
We then need to install the Python dependencies with:
```bash
$ python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
```
And finally configure the service to be run by Systemd. In the
`/etc/systemd/system/cps.service` we need to add:
```bash
Description=Calibre-Web
[Service]
Type=simple
User=root
ExecStart=/var/www/calibre-web/.venv/bin/python /var/www/calibre-web/cps.py
WorkingDirectory=/var/www/calibre-web
[Install]
WantedBy=multi-user.target"; } > /etc/systemd/system/cps.service
```
And we also enable this to run on reboot:
```bash
$ systemctl enable cps.service
```
### Setup a new MOTD ### Setup a new MOTD
When you SSH into the Raspberry Pi, you can enable a nice welcome message.
This is possible bu putting the following in the `/etc/motd/` file:
```
____ _ _ _ _ _ _
| _ \(_) | | (_) | | | |
| |_) |_| |__ | |_ ___ | |_ ___ ___| |__ __ _
| _ <| | '_ \| | |/ _ \| __/ _ \/ __| '_ \ / _` |
| |_) | | |_) | | | (_) | || __/ (__| | | | (_| |
|____/|_|_.__/|_|_|\___/ \__\___|\___|_| |_|\__,_|
Digital books need libraries too
```
### Conclusion
That's it! You should now reboot your Raspberry Pi with:
```bash
$ reboot
```
You can now follow the [post-installation] steps.
[post-installation]: #post-installation