Another stab at Bibliotecha usability
This commit is contained in:
parent
e1b6a3546e
commit
6e6a6d6b9d
1
.gitignore
vendored
1
.gitignore
vendored
@ -1,3 +1,4 @@
|
||||
site/
|
||||
src/
|
||||
.venv/
|
||||
docs/files
|
||||
|
||||
BIN
docs/img/pi.png
Normal file
BIN
docs/img/pi.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 536 KiB |
BIN
docs/img/router.png
Normal file
BIN
docs/img/router.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 650 KiB |
159
docs/index.md
159
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
|
||||
system.
|
||||
[Raspberry Pi] single board computer and the Debian based [Raspberry Pi OS].
|
||||
|
||||
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.*
|
||||
|
||||
|
||||
|
||||
*Below: And here we plug that cable into the Raspberry pi.*
|
||||
|
||||
|
||||
|
||||
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 operating system onto the SD card which you will plug into your
|
||||
Raspberry Pi. You can also use the ["dd" command].
|
||||
[Raspberry Pi OS] (formerly "Raspian Buster") is the current latest recommended
|
||||
version of the standard Raspberry Pi operating system. [Etcher] is a useful and
|
||||
simple tool for flashing the operating system onto the SD card which you will
|
||||
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/
|
||||
[raspbian buster]: https://www.raspberrypi.org/blog/buster-the-new-version-of-raspbian/
|
||||
[raspberry pi os]: https://www.raspberrypi.org/documentation/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 `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 the `System Options > 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.
|
||||
- Follow the `System 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 `<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.
|
||||
- Follow the `Advanced 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.
|
||||
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
- 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
|
||||
|
||||
@ -8,3 +8,4 @@ nav:
|
||||
|
||||
markdown_extensions:
|
||||
- toc
|
||||
- admonition
|
||||
|
||||
Loading…
Reference in New Issue
Block a user