Taking another run at the manual once more

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
+It is now time to run the automatic installation. This script will install and
-installation. This script will install and configure all the necessary moving
+configure all the necessary moving parts of Bibliotecha.
-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.
+`Bibliotecha`. You should wait a few minutes for this hotspot to become
-You should be able to connect to this Wifi. It is not password protected.
+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