varia/bibliotecha-manual
14
0
Fork 1
Code Issues 2 Pull Requests Releases Activity

Run formatter over the docs

Browse Source
This commit is contained in:
Luke Murphy 2020-02-12 23:59:14 +01:00
parent d10533ba20
commit 93141590b7
No known key found for this signature in database
GPG Key ID: 5E2EF5A63E3718CC
1 changed files with 65 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

127
docs/index.md
View File

@ -38,12 +38,12 @@ 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 flashing the operating system onto the SD card which you will plug into your
Raspberry Pi. Raspberry Pi.
[Raspberry Pi]: https://www.raspberrypi.org/ [raspberry pi]: https://www.raspberrypi.org/
[official setup documentation]: https://www.raspberrypi.org/documentation/setup/ [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/ [raspbian]: https://www.raspberrypi.org/documentation/raspbian/
[Raspbian Buster]: https://www.raspberrypi.org/blog/buster-the-new-version-of-raspbian/ [raspbian buster]: https://www.raspberrypi.org/blog/buster-the-new-version-of-raspbian/
[Etcher]: https://www.balena.io/etcher/ [etcher]: https://www.balena.io/etcher/
## Pre-installation ## Pre-installation
@ -72,34 +72,38 @@ We should then perform a number of steps within the [raspi-config] tool:
$ raspi-config $ raspi-config
``` ```
* Change the user password - 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 - Choose the `Change User Password` option.
* Follow the ``Network Options > Hostname`` options. - It is important to configure your Raspberry Pi with a secure passphrase.
* The hostname will be the name that identifies the Raspberry Pi A [diceware passphrase] is a recommended approach for choosing a
on the local network. sufficiently strong passphrase.
* Configure predictable network interfaces - Choose a hostname
* 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 `Network Options > Hostname` options.
* Follow the ``Localisation Options > Change Locale`` options. - The hostname will be the name that identifies the Raspberry Pi
* It is recommended to ensure that the ``en_GB.UTF-8 UTF-8`` locale on the local network.
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 - Configure predictable network interfaces
* Follow the ``Advanced Options > Expand filesystem`` options.
* This allows more space on the SD card to be used. This is important - Follow the `Network Options > Network interface names` options.
for when you will start to place more and more digital books in your - It is important to enable predictable network interface names
Bibliotecha. 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.
- 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 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: should do. If not, you can also run this from the command-line:
@ -135,15 +139,15 @@ The script will automatically reboot your Raspberry Pi when it is finished.
If you run into any issues, please see the [Troubleshooting section]. 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 [source is available]: https://git.vvvvvvaria.org/varia/bibliotecha-install/src/branch/master/bibliotecha.sh
## Post-installation ## Post-installation
After rebooting, there should be a Wifi hotspot available with the name After rebooting, there should be a Wifi hotspot available with the name
`Bibliotecha`. You should wait a few minutes for this hotspot to become `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. 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 Once connected you should be directed to the so-called "captive portal" of the
@ -179,8 +183,8 @@ The default adminstration password login details are:
You should change these details to secure your adminstration account. You should change these details to secure your adminstration account.
[http://bibliotecha.library]: http://bibliotecha.library [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 ## Maintaining a Community Library
@ -188,11 +192,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 your community would like to maintain the library. You should ask yourself some
questions: 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 maintaing the system?
## Understanding Bibliotecha Networking ## Understanding Bibliotecha Networking
@ -202,14 +206,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 useful skill to have. Overall, Bibliotecha is made up of the following programs
and configurations: 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 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 is first serving a Wireless access point (Hostap) which your devices can
@ -305,7 +309,7 @@ $ .venv/bin/pip install -r requirements.txt
$ systemctl start cps $ 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/ [mailing list]: https://we.lurk.org/postorius/lists/bibliotecha.we.lurk.org/
## Manual installation ## Manual installation
@ -354,7 +358,6 @@ $ apt install -y \
Afterwards, we'll make sure to stop these services running while we work on the Afterwards, we'll make sure to stop these services running while we work on the
installation right now. We can do that with: installation right now. We can do that with:
```bash ```bash
$ systemctl stop dnsmasq $ systemctl stop dnsmasq
$ systemctl stop hostapd $ systemctl stop hostapd
@ -394,8 +397,8 @@ naming conventions which we rely on.
For the following steps, I assume the following: 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 We then configure the ethernet interface. We put the following in
`/etc/network/interfaces.d/enx78e7d1ea46da`: `/etc/network/interfaces.d/enx78e7d1ea46da`:
@ -411,7 +414,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 router, you will receive a dynamic IP from that router. This makes it easy to
reach the internet later. 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`: `/etc/network/interfaces.d/wlp2s0`:
``` ```
@ -443,7 +446,7 @@ dhcp-authoritative
``` ```
This configuration sets up a local `.library` domain and a range of IP 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. 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. This is useful for the purposes of the captive portal configuration later on.
@ -574,7 +577,7 @@ We then need to install the Python dependencies with:
$ 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. And finally configure the service to be run by Systemd.
Create the file `/etc/systemd/system/cps.service` and add these lines to it: Create the file `/etc/systemd/system/cps.service` and add these lines to it:
```bash ```bash
@ -635,9 +638,9 @@ You can now follow the [post-installation] steps.
Bibliotecha is made up of the following projects: 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! All contributions are welcome!
@ -647,10 +650,10 @@ You can also find us on the [mailing list].
## Acknowledgements ## 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