Write the manual guide

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