|
|
|
@ -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 |
|
|
|
|
