diff --git a/docs/index.md b/docs/index.md index 691b055..939e8c7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ # Bibliotecha Manual -> [bibliotecha.info/](https://bibliotecha.info/) +> [Bibliotecha - Digital books need libraries too](https://bibliotecha.info/) > Bibliotecha is a framework to facilitate the local distribution of digital > publications within a small community. It relies on a microcomputer running @@ -17,14 +17,137 @@ ## Introduction -Welcome to the Bibliotecha manual! +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 +community. ## Prerequisites +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 +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. + +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 operating system. [Etcher] is a useful and simple tool for +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/ + ## Pre-installation -## 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. + +Firstly, we switch our user to the root account: + +```bash +$ sudo -i +``` + +We then perform the initial system update and upgrade: + +```bash +$ apt update +$ apt upgrade +``` + +We should then perform a number of steps within the [raspi-config] tool: + +```bash +$ raspi-config +``` + +* Change the user password + * Choose the ``Change User Password`` option. + * 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 + * Follow the ``Network Options > Hostname`` options. + * The hostname will be the name that identifies the Raspberry Pi + on the local network. + +* Configure predictable network interfaces + * Follow the ``Network Options > Network interface names`` options. + * 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 + * 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 ```` 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 +should do. If not, you can also run this from the command-line: + +```bash +$ 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! + +[raspi-config]: https://www.raspberrypi.org/documentation/configuration/raspi-config.md +[diceware passphrase]: https://www.rempe.us/diceware/#eff + +## Automated installation + +Once you've completed all the previous steps, it is time to run the automatic +installation. This script will install and configure all the necessary moving +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 + +```bash +$ sudo -i +$ curl https://git.vvvvvvaria.org/varia/bibliotecha-install/raw/branch/master/bibliotecha.sh | bash +``` ## 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. +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]. + +[http://bibliotecha.library]: http://bibliotecha.library + ## Troubleshooting + +* TODO + +## Manual installation + +* TODO