From 8e6c03088f645040b5bafa28c60067200aff20e1 Mon Sep 17 00:00:00 2001 From: Luke Murphy Date: Tue, 9 Jul 2019 15:13:11 +0200 Subject: [PATCH] Write the manual guide --- docs/index.md | 341 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 338 insertions(+), 3 deletions(-) diff --git a/docs/index.md b/docs/index.md index 11520d9..0ec06a9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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]. -### 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 + +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 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 -#### 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 +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 [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. +### 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 + +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 + +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 + +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 + +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 + +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 -### 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 + +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 + +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 + +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 + +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