Use image and other URL

We're not going to be using HEAD anymore.

See varia/bibliotecha-install#4.

.gitignore

@@ -1,3 +1,4 @@
 site/
 src/
 .venv/
+docs/files

README.md

@@ -1,10 +1,10 @@
-# Manual.bibliotecha.info
+# manual.bibliotecha.info
 
 The manual for Bibliotecha.
 
 > https://manual.bibliotecha.info
 
-# Contribute to the Manual
+# Contribute to the manual
 
 ```
 $ python3 -m venv .venv && source .venv/bin/activate

docs/index.md

@@ -17,33 +17,104 @@ Welcome to the Bibliotecha manual! This guide serves as a human-friendly
 document for setting up an offline-first local library for yourself and your
 community.
 
+## Go Slow, Make a Plan
+
+There is nothing really easy about diving into this system administration work
+and getting things up and running but on the other hand there is nothing so
+complicated that it cannot be figured out. In short: you can do it!
+
+The two most important things to take into consideration before starting are
+
+- Choosing a "route" through this documentation (see just below).
+- Reading the [Prerequisites] section very closely and trying to
+  understand, **before you dive in**, how things will work with your Raspberry
+  Pi and how it is setup and connected to the internet.
+
+There are 3 routes you can take through this documentation:
+
+- **Cloning**: Skipping the entire thing and simply cloning a pre-made copy of
+  a Bibliotecha SD-card onto your new SD-card. You can then plug the SD-card
+  into your Raspberry Pi and Bibliotecha will be ready to go. Skip to the
+  [Cloning] section for more. This is the *moving really fast and don't have
+  time* option.
+
+- **Automated**: You follow the documentation below: [Prerequisites],
+  [Pre-installation] and finally [Automated Installation]. This allows you do
+  to the initial setup and then a run convenient installation script which
+  takes care of installing Bibliotecha. This is the *moving fast but still want
+  to be involved with the process* option.
+
+- **Manual**: You follow the documentation below: [Prerequisites],
+  [Pre-installation] and finally [Manual Installation]. You do everything
+  yourself to get from start to finish. Everything that would be done in the
+  automated script, you do yourself. This is the *I have time and want to learn
+  a lot* option.
+
+[automated installation]: #automated-installation
+[cloning]: #cloning
+[pre-installation]: #pre-installation
+[prerequisites]: #prerequisites
+
 ## Prerequisites
 
 Bibliotecha is made specifically for use on the cheap and widely accessible
-[Raspberry Pi] single board computer and Debian based [Raspbian] operating
+[Raspberry Pi] single board computer and the Debian based [Raspberry Pi OS].
-system.
 
 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.
 
+!!! warning
+
+    You **must** use an Ethernet cable to connect your Raspberry Pi to your
+    router and not use the Wifi connection. This is because the Bibliotecha
+    install process will overwrite the Wifi configuration. So, you also
+    **must** have access to your router before going further.
+
+Here is an example of what we did.
+
+*Below: Here we plug the gray ethernet cable into the router.*
+
+![Router](img/router.png)
+
+*Below: And then we plug that same gray ethernet cable into the Raspberry Pi.*
+
+![Pi](img/pi.png)
+
+!!! note
+
+    The ethernet cable is not required after you finish the installation
+    of Bibliotecha! Your Bibliotecha can now operate independent of an internet
+    connection and offers its own Wifi access point. So, the ethernet cable is only
+    required for the installation process. Later, if you need to do an update or
+    some maintenance which requires an internet connection, you can plug it back in
+    and [make sure to check this tip].
+
 The current latest [Raspberry Pi 3 B+] model is recommended. This model is
 chosen because it offers a built-in wireless card for convenient networking and
 a sufficient memory allowance of 1GB. It is possible to use other models of
 board but they should at least provide these guarantees.
 
-[Raspbian Buster] is the current latest recommended version of the standard
+[Raspberry Pi OS] (formerly "Raspian Buster") is the current latest recommended
-Raspberry Pi operating system. [Etcher] is a useful and simple tool for
+version of the standard Raspberry Pi operating system. [Etcher] is a useful and
-flashing the operationg system onto the SD card which you will plug into your
+simple tool for flashing the operating system onto the SD card which you will
-Raspberry Pi.
+plug into your Raspberry Pi. You can also use the [dd command].
 
-[Raspberry Pi]: https://www.raspberrypi.org/
+Here is the `dd` command we use:
+
+```bash
+$ sudo lsblk  # to see the value for the `of` argument (e.g. /dev/mmcblk0)
+$ sudo dd bs=4M if=2020-08-20-raspios-buster-armhf-lite.img of=<YOUR-DEVICE-HERE> status=progress conv=fsync
+```
+
+[dd command]: https://www.raspberrypi.org/documentation/installation/installing-images/linux.md
+[etcher]: https://www.balena.io/etcher/
+[make sure to check this tip]: #i-cannot-connect-to-the-internet-from-the-raspberry-pi
 [official setup documentation]: https://www.raspberrypi.org/documentation/setup/
-[Raspberry Pi 3 B+]: https://www.raspberrypi.org/products/raspberry-pi-3-model-b/
+[raspberry pi 3 b+]: https://www.raspberrypi.org/products/raspberry-pi-3-model-b/
-[Raspbian]: https://www.raspberrypi.org/documentation/raspbian/
+[raspberry pi os]: https://www.raspberrypi.org/documentation/raspbian/
-[Raspbian Buster]: https://www.raspberrypi.org/blog/buster-the-new-version-of-raspbian/
+[raspberry pi]: https://www.raspberrypi.org/
-[Etcher]: https://www.balena.io/etcher/
 
 ## Pre-installation
 
@@ -66,42 +137,55 @@ $ apt update
 $ apt upgrade
 ```
 
+This step may be not needed but it has been reported a few times. You need to
+unblock the Wifi device. In order to do this, you'll need to run the following.
+
+```bash
+$ apt install -y rfkill
+$ rfkill unblock wlan
+```
+
 We should then perform a number of steps within the [raspi-config] tool:
 
 ```bash
 $ raspi-config
 ```
 
-* Change the user password
+- Change the user password
-    * Choose the ``Change User Password`` option.
+    - Choose the `System Options > Password` option.
-    * It is important to configure your Raspberry Pi with a secure passphrase.
+    - It is important to configure your Raspberry Pi with a secure passphrase.
       A [diceware passphrase] is a recommended approach for choosing a
       sufficiently strong passphrase.
 
-* Choose a hostname
+- Choose a hostname
-    * Follow the ``Network Options > Hostname`` options.
+    - Follow the `System Options > Hostname` options.
-    * The hostname will be the name that identifies the Raspberry Pi
+    - The hostname will be the name that identifies the Raspberry Pi on the
-      on the local network.
+      local network.
 
-* Configure predictable network interfaces
+- Configure predictable network interfaces
-    * Follow the ``Network Options > Network interface names`` options.
+    - Follow the `Advanced Options > Network Interface Names` options.
-    * It is important to enable predictable network interface names
+    - It is important to enable predictable network interface names
       so that the automatic installation script can detect which network
       interfaces are in use.
 
-* Configure the localisation
+- Expand the SD card partition
-    * Follow the ``Localisation Options > Change Locale`` options.
+    - Follow the `Advanced Options > Expand filesystem` options.
-    * It is recommended to ensure that the ``en_GB.UTF-8 UTF-8`` locale
+    - This allows more space on the SD card to be used. This is important
-      is selected. This is the default. Once this is selected, select ``<Ok>`` on the
-      two following dialogs to generate the locale.
-
-* Expand the SD card partition
-    * Follow the ``Advanced Options > Expand filesystem`` options.
-    * This allows more space on the SD card to be used. This is important
       for when you will start to place more and more digital books in your
       Bibliotecha.
 
-The Raspi-config interface then ask you to restart the Raspberry Pi which you
+- Configure the localisation
+    - Follow the `Localisation Options > Change Locale` options.
+    - It is recommended to ensure that the `en_GB.UTF-8 UTF-8` locale
+      is selected. This is the default. Once this is selected, select `<Ok>` on the
+      two following dialogs to generate the locale.
+
+- Configure WLAN country
+    - Follow the `Localisation Options > Change WLAN Country` options.
+    - This is actually really important or the `rfkill` related step above
+      will keep your Wireless device disabled.
+
+The Raspi-config interface then asks you to restart the Raspberry Pi which you
 should do. If not, you can also run this from the command-line:
 
 ```bash
@@ -111,6 +195,11 @@ $ reboot
 Remember, you will need to use your new user passphrase to access the Raspberry
 Pi after rebooting it. Make sure you store this passphrase somewhere safe!
 
+Also, please note, if you did run the `rfkill` commands above, please check
+that when you reboot, the message shown when you log back in does not say that
+the Wifi device is still blocked. You may need to fiddle with `rfkill` and the
+`raspi-config` WLAN country settings.
+
 [raspi-config]: https://www.raspberrypi.org/documentation/configuration/raspi-config.md
 [diceware passphrase]: https://www.rempe.us/diceware/#eff
 
@@ -135,20 +224,20 @@ 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
+[manual installation]: #manual-installation
-[Troubleshooting section]: #troubleshooting
+[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`. You should wait a few minutes for this hotspot to become
-available. This Wifi access point is being served from the Raspberry Pi.  You
+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 portal" of the
 Bibliotecha where it explains how to enter the library and use it. The library
-should be available at [http://bibliotecha.library].
+should be available locally at [http://bibliotecha.library].
 
 It is recommended to customise your captive portal page to suite your own
 needs. This file is available in the `/var/www/bibliotecha/index.html`
@@ -165,7 +254,7 @@ the following path:
 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
+decide whether to allow uploading, anonymous browsing and allowing public
 registrations. These depend on your context and for who you will serve the
 library to.
 
@@ -179,8 +268,8 @@ The default adminstration password login details are:
 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]: https://github.com/janeczku/calibre-web/
-[Calibre-web wiki]: https://github.com/janeczku/calibre-web/wiki/Configuration
+[calibre-web wiki]: https://github.com/janeczku/calibre-web/wiki/Configuration
 
 ## Maintaining a Community Library
 
@@ -188,11 +277,11 @@ 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.
+- Who will be the digital librarians? The catalogue will need care.
-  * Will you allow public registrations? Will you allow public uploads?
+- Will you allow public registrations? Will you allow public uploads?
-  * How will you publicise the library within the local context?
+- How will you publicise the library within the local context?
-  * What kind of library do you want to create? What are the themes?
+- What kind of library do you want to create? What are the themes?
-  * Who will be responsible for maintaing the system?
+- Who will be responsible for maintaining the system?
 
 ## Understanding Bibliotecha Networking
 
@@ -202,14 +291,14 @@ 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/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
+- [/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
+- [Hostap](https://wiki.debian.org/hostap): The Wifi access point provider
-  * [Dnsmasq](https://wiki.debian.org/HowTo/dnsmasq): The DNS and DHCP server
+- [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
+- [Dhcpcd](https://manpages.debian.org/buster/dhcpcd5/dhcpcd.8.en.html): The DHCP client
-  * [Calibre](https://calibre-ebook.com/): The library database
+- [Calibre](https://calibre-ebook.com/): The library database
-  * [Calibre-web](https://github.com/janeczku/calibre-web/): The library web application
+- [Calibre-web](https://github.com/janeczku/calibre-web/): The library web application
-  * [Lighttpd](https://www.lighttpd.net/): The web server
+- [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
@@ -236,8 +325,14 @@ 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 someone is online, you may also find us lurking in the `#bibliotecha`
+channel on IRC. Here is [a web page you can use] to connect without having to do
+any account sign-up.
+
 All of the following commands should be run as the root user.
 
+[a web page you can use]: https://webchat.freenode.net/?channel=#varia
+
 #### I cannot connect to the internet from the Raspberry Pi
 
 If you are connecting an Ethernet cable to your Bibliotecha in order to connect
@@ -295,18 +390,86 @@ $ 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:
+cable first. Then, you'll need to check to see what are the latest releases
+from Calibre-web on [their release page]. Once you have a fair idea of the
+version you'd like to upgrade to (careful, skipping over multiple versions can
+easily break things, so better go one by one and check which one works each
+step of way), then start off with turning off the program and getting into the
+installation directory.
 
 ```bash
 $ systemctl stop cps
 $ cd /var/www/calibre-web
-$ git pull origin master
+```
+
+Now, you'll want to pull down all the tags from the remote repository.
+
+```bash
+$ git fetch origin master -a
+```
+
+Then list all those tags.
+
+```bash
+$ git tag -l
+```
+
+At this point you should see your version number listed somewhere. You can
+check check out to that tag, install the updated dependencies and restart the
+program.
+
+```bash
+$ git checkout 0.6.9  # latest version as of November 2020
 $ .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/
+[their release page]: https://github.com/janeczku/calibre-web/releases
+
+## Cloning
+
+We provide a pre-made SD-card for Bibliotecha which you can copy onto your own
+SD-card and get moving fast. This can be useful if you don't want to dive into
+all the system adminstration work.
+
+!!! warning
+
+    We currently offer a 32 GB image, meaning, if you want to use it, you
+    **must also have a 32 GB SD-card**. If you would like other options, please
+    get in touch.
+
+Download
+[bibliotecha.img](https://vvvvvvaria.org/~luke/bibliotecha/bibliotecha.img). It
+is greater than 30 GBs in size, so it could take some time! Then unzip the file
+with the following command.
+
+Plug in your own SD-card into your laptop. Run the `lsblk` command and take
+note of the path available for the card (e.g. `/dev/mmcblk0`). See the [dd
+documentation] for more help.
+
+Start copying the image onto your SD-card with the `dd` command.
+
+```bash
+$ sudo dd bs=4M if=bibliotecha.img of=/dev/mmcblk0 status=progress conv=fsync`
+```
+
+Then plug your SD-card out of your laptop and plug it into your Raspberry Pi and turn the Pi on.
+
+You should now be able to log into the Pi using SSH or via a screen using the following credentials:
+
+- **username**: pi
+- **password**: bibliotecha
+
+Please change your password by running `sudo raspi-config` and choosing `System
+Options > Password`.
+
+You can now follow the [post-installation] steps but please note, you will
+**not** be required to configure the Calibre-web installation because it is
+already done!
+
+[dd documentation]: https://www.raspberrypi.org/documentation/installation/installing-images/linux.md
 
 ## Manual installation
 
@@ -354,7 +517,6 @@ $ apt install -y \
 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
@@ -389,19 +551,19 @@ $ 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
+interface is the one beginning with "wl". These are the predictable interface
 naming conventions which we rely on.
 
 For the following steps, I assume the following:
 
-  * Ethernet: enx78e7d1ea46da
+- Ethernet: enx78e7d1ea46da
-  * Wireless: wlp2s0
+- Wireless: wlp2s0
 
 We then configure the ethernet interface. We put the following in
 `/etc/network/interfaces.d/enx78e7d1ea46da`:
 
 ```bash
-auto eth0
+auto enx78e7d1ea46da
 allow-hotplug enx78e7d1ea46da
 iface enx78e7d1ea46da inet dhcp
 ```
@@ -411,7 +573,7 @@ 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
+We then configure the wireless interface. We put the following in
 `/etc/network/interfaces.d/wlp2s0`:
 
 ```
@@ -443,7 +605,7 @@ 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
+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.
 
@@ -518,14 +680,13 @@ are then pointed to the Calibre-web installation.
 
 ### Install and Configure Calibre
 
-Calibre is responsible for maintaining the underyling database of the library. We
+Calibre is responsible for maintaining the underlying database of the library. We can install it with:
-can install it with:
 
 ```bash
-$ apt install -y calibre
+$ apt install -y calibre --no-install-recommends
 ```
 
-This will take some time as there are man required packages. Once it if
+This will take some time as there are many required packages. Once it is
 finished, you will then need to create a new database for the Calibre-web
 installation to use.
 
@@ -539,7 +700,15 @@ $ /usr/bin/calibredb restore_database --really-do-it --with-library /opt/calibre
 ### Configure the Captive Portal
 
 When we connect to the Bibliotecha wireless access point, we will be directed
-to a splash page where we are introduced to the library. We need to set that up:
+to a splash page where we are introduced to the library.
+
+First make sure we have all dependencies:
+
+```bash
+$ apt install -y wget git ghostscript python3-venv
+```
+
+Then create a folder for our splash page:
 
 ```bash
 $ mkdir /var/www/bibliotecha
@@ -548,7 +717,6 @@ $ mkdir /var/www/bibliotecha
 And then we download the default page into location:
 
 ```bash
-$ apt install -y wget git python3-venv
 $ wget https://git.vvvvvvaria.org/varia/bibliotecha-captive-portal/raw/branch/master/index.html -O /var/www/bibliotecha/index.html
 ```
 
@@ -568,13 +736,25 @@ $ git clone https://github.com/janeczku/calibre-web /var/www/calibre-web
 $ cd /var/www/calibre-web
 ```
 
+Then, looking at the [Calibre-web release page], we can choose a version we
+would like to install. As of November 2020, the latest version is 0.6.9, so
+we can check that version out with the following:
+
+```bash
+$ git fetch origin master -a
+$ git tag -l
+$ git checkout 0.6.9
+```
+
 We then need to install the Python dependencies with:
 
 ```bash
-$ python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
+$ python3 -m venv .venv
+$ .venv/bin/pip install -r requirements.txt
 ```
 
 And finally configure the service to be run by Systemd.
+
 Create the file `/etc/systemd/system/cps.service` and add these lines to it:
 
 ```bash
@@ -602,6 +782,8 @@ We should also ensure that the correct ownership permissions are configured:
 $ chown -R www-data: /var/www/calibre-web
 ```
 
+[calibre-web release page]: https://github.com/janeczku/calibre-web/releases
+
 ### Setup a new MOTD
 
 When you SSH into the Raspberry Pi, you can enable a nice welcome message.
@@ -635,9 +817,9 @@ You can now follow the [post-installation] steps.
 
 Bibliotecha is made up of the following projects:
 
-  * [bibliotecha-install](https://git.vvvvvvaria.org/varia/bibliotecha-install)
+- [bibliotecha-install](https://git.vvvvvvaria.org/varia/bibliotecha-install)
-  * [bibliotecha-manual](https://git.vvvvvvaria.org/varia/bibliotecha-manual)
+- [bibliotecha-manual](https://git.vvvvvvaria.org/varia/bibliotecha-manual)
-  * [bibliotecha-captive-portal](https://git.vvvvvvaria.org/varia/bibliotecha-captive-portal)
+- [bibliotecha-captive-portal](https://git.vvvvvvaria.org/varia/bibliotecha-captive-portal)
 
 All contributions are welcome!
 
@@ -647,10 +829,12 @@ You can also find us on the [mailing list].
 
 ## Acknowledgements
 
-* The [Calibre] project
+- The [Calibre] project
-* The [Calibre-web] project
+- The [Calibre-web] project
 
-[Calibre]: https://calibre-ebook.com
+[calibre]: https://calibre-ebook.com
-[Calibre-web]: https://github.com/janeczku/calibre-web
+[calibre-web]: https://github.com/janeczku/calibre-web
 
-Contributors to Bibliotecha have been Yoana Buzova, Lasse van den Bosch Christensen, Andre Castro, Lucia Dossin, Max Dovey, Michaela Lakova, Luke Murphy and Roel Roscam Abbing 
+Contributors to Bibliotecha have been Yoana Buzova, Lasse van den Bosch
+Christensen, Andre Castro, Lucia Dossin, Max Dovey, Michaela Lakova, Luke
+Murphy and Roel Roscam Abbing

mkdocs.yml

@@ -8,3 +8,4 @@ nav:
 
 markdown_extensions:
   - toc
+  - admonition