Another stab at Bibliotecha usability

.gitignore

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

docs/index.md

@@ -17,32 +17,92 @@ 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 grey ethernet cable into our Router.*
+
+![Router](img/router.png)
+
+*Below: And here we plug that cable into the Raspberry pi.*
+
+![Pi](img/pi.png)
+
 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 operating 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. You can also use the ["dd" command].
+plug into your Raspberry Pi. You can also use the ["dd" command].
+
+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
+```
 
 [raspberry pi]: https://www.raspberrypi.org/
 [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/
+[raspberry pi os]: 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/
 ["dd" command]: https://www.raspberrypi.org/documentation/installation/installing-images/linux.md
 
@@ -82,43 +142,38 @@ $ raspi-config
 ```
 
 - Change the user password
-
+    - Choose the `System Options > Password` option.
-  - Choose the `Change User 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
-    A [diceware passphrase] is a recommended approach for choosing a
+      sufficiently strong passphrase.
-    sufficiently strong passphrase.
 
 - Choose a hostname
-
+    - Follow the `System Options > Hostname` options.
-  - Follow the `Network Options > Hostname` options.
+    - The hostname will be the name that identifies the Raspberry Pi on the
-  - The hostname will be the name that identifies the Raspberry Pi
+      local network.
-    on the local network.
 
 - Configure predictable network interfaces
-
+    - Follow the `Advanced Options > Network Interface Names` options.
-  - Follow the `Network 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
-    so that the automatic installation script can detect which network
+      interfaces are in use.
-    interfaces are in use.
-
-- 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.
 
 - Expand the SD card partition
-  - Follow the `Advanced Options > Expand filesystem` options.
+    - Follow the `Advanced Options > Expand filesystem` options.
-  - This allows more space on the SD card to be used. This is important
+    - 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
+      for when you will start to place more and more digital books in your
-    Bibliotecha.
+      Bibliotecha.
+
+- 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:
@@ -363,6 +418,32 @@ $ systemctl start cps
 [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. 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.
+
+The process is as follows:
+
+- Download [bibliotecha.img](https://manual.bibliotecha.info/files/bibliotecha.img) (32 GBs, will take some time!)
+- Plug in your own SD-card into your laptop
+- Run `lsblk` and take note of the path available for the card (e.g. `/dev/mmcblk0`)
+- Run `sudo dd bs=4M if=bibliotecha.img of=/dev/mmcblk0 status=progress conv=fsync`
+- Plug your SD-card out and 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!
+
 ## Manual installation
 
 It is possible to install Bibliotecha manually. This can be useful and fun if

mkdocs.yml

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