forked from varia/bibliotecha-manual
Write the manual guide
This commit is contained in:
parent
4d0d74b08e
commit
8e6c03088f
341
docs/index.md
341
docs/index.md
@ -231,14 +231,75 @@ 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].
|
||||
|
||||
### The automatic installation script failed
|
||||
All of the following commands should be run as the root user.
|
||||
|
||||
#### I cannot connect to the internet from the Raspberry Pi
|
||||
|
||||
If you are connecting an Ethernet cable to your Bibliotecha in order to connect
|
||||
it to your local router and have access to the internet, then you might notice
|
||||
that the requests do reach their destination.
|
||||
|
||||
Bibliotecha is configured to capture all the network requests it receives and
|
||||
point them to the library interface. You will need to temporarily disable the
|
||||
`dnsmasq` service:
|
||||
|
||||
```bash
|
||||
$ systemctl stop dnsmasq
|
||||
```
|
||||
|
||||
It should then be possible to connect to the wider internet now.
|
||||
|
||||
#### The wireless access point is not available
|
||||
|
||||
The access point is responsibility of the `hostapd` program. You should check
|
||||
the status of the running service with:
|
||||
|
||||
```bash
|
||||
$ systemctl status hostapd
|
||||
```
|
||||
|
||||
If there are errors, you can see the logs with:
|
||||
|
||||
```bash
|
||||
$ journalctl -u hostapd
|
||||
```
|
||||
|
||||
You may also attempt to restart this service afterwards:
|
||||
|
||||
```bash
|
||||
$ systemctl restart hostapd
|
||||
```
|
||||
|
||||
You may also want to inspect the `/etc/hostapd/hostapd.conf` configuration.
|
||||
|
||||
#### I do not receive an IP address when I connect
|
||||
#### Bibliotecha.library is unavailable
|
||||
|
||||
Providing IP addresses is the responsibility of the `dnsmasq` and `dhcpcd`
|
||||
service. You should check the status of `dnsmasq` with:
|
||||
|
||||
```bash
|
||||
$ systemctl status dnsmasq
|
||||
```
|
||||
|
||||
You should make sure that `dhcpcd` is running with:
|
||||
|
||||
```
|
||||
$ 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:
|
||||
|
||||
```bash
|
||||
$ systemctl stop cps
|
||||
$ cd /var/www/calibre-web
|
||||
$ git pull origin master
|
||||
$ .venv/bin/pip install -r requirements.txt
|
||||
$ systemctl start cps
|
||||
```
|
||||
|
||||
[Understanding Bibliotecha Networking]: #understanding-bibliotecha-networking
|
||||
[mailing list]: https://we.lurk.org/postorius/lists/bibliotecha.we.lurk.org/
|
||||
|
||||
@ -251,14 +312,288 @@ networks.
|
||||
|
||||
The following guide follows the steps of the automatic installation script.
|
||||
|
||||
### Changing to Root
|
||||
|
||||
All commands should be run as the root user.
|
||||
|
||||
Change the user to the root user with:
|
||||
|
||||
```bash
|
||||
$ sudo -i
|
||||
```
|
||||
|
||||
### Update the System
|
||||
|
||||
We should update the system before going further:
|
||||
|
||||
```bash
|
||||
$ apt update
|
||||
```
|
||||
|
||||
This makes sure that we have the latest package listing from the online Debian
|
||||
package list.
|
||||
|
||||
### Install Networking Packages
|
||||
|
||||
We then need to install the networking packages that we will need:
|
||||
|
||||
```bash
|
||||
$ apt install -y \
|
||||
dhcpcd \
|
||||
dnsmasq \
|
||||
dnsutils \
|
||||
hostapd \
|
||||
wireless-tools
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
We do want these services to be enabled when we reboot though:
|
||||
|
||||
```bash
|
||||
$ systemctl unmask hostapd
|
||||
$ systemctl enable hostapd
|
||||
$ systemctl enable dnsmasq
|
||||
```
|
||||
|
||||
We'll also want to disable and stop the `avahi-daemon` which we won't be using
|
||||
since we rely on `dnsmasq` to handle our DNS configuration and serving:
|
||||
|
||||
```bash
|
||||
$ systemctl stop avahi-daemon
|
||||
$ systemctl disable avahi-daemon
|
||||
```
|
||||
|
||||
### Configure Network Interfaces
|
||||
|
||||
We now need to configure our network interfaces. The network interfaces
|
||||
correspond to the Ethernet port and the Wireless card. These are how the
|
||||
Raspberry Pi connect to other devices for networking uses.
|
||||
|
||||
We need to learn the names of our network interfaces:
|
||||
|
||||
```bash
|
||||
$ 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
|
||||
naming conventions which we rely on.
|
||||
|
||||
For the following steps, I assume the following:
|
||||
|
||||
* Ethernet: enx78e7d1ea46da
|
||||
* Wireless: wlp2s0
|
||||
|
||||
We then configure the ethernet interface. We put the following in
|
||||
`/etc/network/interfaces.d/enx78e7d1ea46da`:
|
||||
|
||||
```bash
|
||||
auto eth0
|
||||
allow-hotplug enx78e7d1ea46da
|
||||
iface enx78e7d1ea46da inet dhcp
|
||||
```
|
||||
|
||||
This configuration allows the default behaviour for the Ethernet interface.
|
||||
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
|
||||
`/etc/network/interfaces.d/wlp2s0`:
|
||||
|
||||
```
|
||||
auto wlp2s0
|
||||
iface wlp2s0 inet static
|
||||
address 10.0.0.1
|
||||
netmask 255.255.255.0
|
||||
```
|
||||
|
||||
This configuration sets up a static IP address for the wireless interface. We
|
||||
do this so as to put the IP address within the range of the addresses which we
|
||||
allow in the local network. We will configure this range in the following step.
|
||||
|
||||
### Configure Dnsmasq
|
||||
|
||||
In the `/etc/dnsmasq.d/wlp2s0.conf` file, we put the following:
|
||||
|
||||
```bash
|
||||
bogus-priv
|
||||
server=/library/10.0.0.1
|
||||
local=/library/
|
||||
address=/#/10.0.0.1
|
||||
interface=wlp2s0
|
||||
domain=library
|
||||
dhcp-range=10.0.0.50,10.0.0.200,255.255.255.0,12h
|
||||
dhcp-option=3,10.0.0.1
|
||||
dhcp-option=6,10.0.0.1
|
||||
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
|
||||
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.
|
||||
|
||||
### Configure Hostapd
|
||||
|
||||
We need to set up the wireless access point too. In the
|
||||
`/etc/hostapd/hostapd.conf` we add:
|
||||
|
||||
```bash
|
||||
interface=wlp2s0
|
||||
ssid=Bibliotecha
|
||||
hw_mode=g
|
||||
channel=11
|
||||
auth_algs=1
|
||||
```
|
||||
|
||||
We also need to make sure that `hostapd` uses this configuration. We have to
|
||||
ensure that the following is uncommented and present in the
|
||||
`/etc/default/hostapd` file:
|
||||
|
||||
```bash
|
||||
DAEMON_CONF="/etc/hostapd/hostapd.conf"
|
||||
```
|
||||
|
||||
### Configure the Hosts file
|
||||
### Enable Networking Services
|
||||
|
||||
We need to register the library on the network. In the `/etc/hosts` file we put
|
||||
the following at the end of the file after all the other entries:
|
||||
|
||||
```bash
|
||||
10.0.0.1 bibliotecha.library
|
||||
```
|
||||
|
||||
### Install and Configure Lighttpd
|
||||
|
||||
Moving on, we should install the web server which will respond to network
|
||||
requests and return the web pages of the library interface. We can install
|
||||
Lighttpd with:
|
||||
|
||||
```bash
|
||||
$ apt install -y lighttpd
|
||||
```
|
||||
|
||||
When then need to make sure that the following configuration is available in
|
||||
the `/etc/lighttpd/lighttpd.conf` file:
|
||||
|
||||
```bash
|
||||
server.document-root = "/var/www"
|
||||
server.modules += ("mod_proxy",)
|
||||
include "bibliotecha/bibliotecha.conf"
|
||||
```
|
||||
|
||||
When then create the Bibliotecha configuration with:
|
||||
|
||||
```bash
|
||||
$ mkdir /etc/lighttpd/bibliotecha
|
||||
```
|
||||
|
||||
And then make sure the following is in the
|
||||
`/etc/lighttpd/bibliotecha/bibliotecha.conf` file:
|
||||
|
||||
```bash
|
||||
server.error-handler-404 = "/bibliotecha/index.html"
|
||||
$HTTP["host"] == "bibliotecha.library" {
|
||||
proxy.server = ("" => (("host" => "127.0.0.1", "port" => "8083")))'
|
||||
}
|
||||
```
|
||||
|
||||
This ensures that all unknown requests are pointed to the captive portal page
|
||||
of Bibliotecha. And when we request the `http://bibliotecha.library` domain, we
|
||||
are then pointed to the Calibre-web installation.
|
||||
|
||||
### Install and Configure Calibre
|
||||
|
||||
Calibre is responsible for maintaining the underyling database of the library. We
|
||||
can install it with:
|
||||
|
||||
```bash
|
||||
$ apt install -y calibre
|
||||
```
|
||||
|
||||
This will take some time as there are man required packages. Once it if
|
||||
finished, you will then need to create a new database for the Calibre-web
|
||||
installation to use.
|
||||
|
||||
We should run the following:
|
||||
|
||||
```bash
|
||||
$ mkdir /opt/calibre-database
|
||||
$ /usr/bin/calibredb restore_database --really-do-it /opt/calibre-database
|
||||
```
|
||||
|
||||
### Install and Configure Calibre-web
|
||||
|
||||
We now setup the Calibre-web installation. We first get a copy of the source with:
|
||||
|
||||
```bash
|
||||
$ mkdir /var/www/calibre-web
|
||||
$ git clone https://github.com/janeczku/calibre-web /var/ww/calibre-web
|
||||
$ cd /var/www/calibre-web
|
||||
```
|
||||
|
||||
We then need to install the Python dependencies with:
|
||||
|
||||
```bash
|
||||
$ python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
|
||||
```
|
||||
|
||||
And finally configure the service to be run by Systemd. In the
|
||||
`/etc/systemd/system/cps.service` we need to add:
|
||||
|
||||
```bash
|
||||
Description=Calibre-Web
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=root
|
||||
ExecStart=/var/www/calibre-web/.venv/bin/python /var/www/calibre-web/cps.py
|
||||
WorkingDirectory=/var/www/calibre-web
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target"; } > /etc/systemd/system/cps.service
|
||||
```
|
||||
|
||||
And we also enable this to run on reboot:
|
||||
|
||||
```bash
|
||||
$ systemctl enable cps.service
|
||||
```
|
||||
|
||||
### Setup a new MOTD
|
||||
|
||||
When you SSH into the Raspberry Pi, you can enable a nice welcome message.
|
||||
|
||||
This is possible bu putting the following in the `/etc/motd/` file:
|
||||
|
||||
```
|
||||
____ _ _ _ _ _ _
|
||||
| _ \(_) | | (_) | | | |
|
||||
| |_) |_| |__ | |_ ___ | |_ ___ ___| |__ __ _
|
||||
| _ <| | '_ \| | |/ _ \| __/ _ \/ __| '_ \ / _` |
|
||||
| |_) | | |_) | | | (_) | || __/ (__| | | | (_| |
|
||||
|____/|_|_.__/|_|_|\___/ \__\___|\___|_| |_|\__,_|
|
||||
|
||||
Digital books need libraries too
|
||||
```
|
||||
|
||||
### Conclusion
|
||||
|
||||
That's it! You should now reboot your Raspberry Pi with:
|
||||
|
||||
```bash
|
||||
$ reboot
|
||||
```
|
||||
|
||||
You can now follow the [post-installation] steps.
|
||||
|
||||
[post-installation]: #post-installation
|
||||
|
||||
Loading…
Reference in New Issue
Block a user