Step 4 of 8

Install BiblioViva

This step installs BiblioViva on the computer prepared in the previous steps, with a single command to copy into the terminal. The setup.sh program checks the computer, installs Docker if it is missing, asks a few questions, starts BiblioViva and writes the address to open in the browser. It takes 5 to 15 minutes, mostly waiting for BiblioViva to download [VERIFY: times to measure on a Raspberry Pi 4 with an SD card].

PC with Linux and the local network

Docker is the program that runs BiblioViva in a closed container, separate from the rest of the computer (see the glossary).

Requirements

The terminal of the BiblioViva computer, opened in the step Connect to the computer.
The computer connected to the internet.
The password of the computer's user, written down in the step Prepare the computer: it is needed by sudo, the command that gives the program administrator rights.
No other data: the local network requires neither an account nor a key.

Procedure

Start the program

Copy the following command.

curl -fsSL https://raw.githubusercontent.com/itotm/biblioviva/main/setup.sh | bash -s -- --lang en

Paste it into the terminal and press Enter (how to paste a command is explained in Connect to the computer). The terminal writes the title "BiblioViva installation" and the program starts checking the computer.

Note. The --lang en option makes the program write in English; without it the program uses the computer's language.

The program downloads BiblioViva's configuration files from its public repository, and the programs' images, and writes everything in the user's biblioviva folder. The program's text can be read before running it: setup.sh.

Install Docker, when it is missing

On a freshly prepared computer Docker is not there. In that case the program says so and asks a question.

Docker is not installed. The program installs it with Docker's official script (https://get.docker.com): it takes a few minutes and the user's password.
Install Docker now? [Y/n]

Press Enter (or Y) to install Docker. Answering n stops the program.
When sudo asks for the password, type the user's password and press Enter. While it is typed nothing appears, not even asterisks: this is normal.
Wait. The installation of Docker writes many lines and takes a few minutes. At the end the program writes: "Docker is installed. To use the docker command without sudo, close the terminal and connect again at the end." The installation of BiblioViva goes on without interruption.

Note. The sentence about closing the terminal refers to the moment the installation is finished: then close the terminal and connect again as in the step Connect to the computer. Until then nothing needs to be done. If Docker was already installed, the sentence does not appear.

Answer the questions

The questions appear in the following order. The program repeats the question when the answer is not valid ("Invalid answer.").

How to reach BiblioViva

How do the library's computers and phones reach BiblioViva?
  1) With Tailscale: secure address (HTTPS), camera, phones, outside the school too. Needs a free Tailscale account.
  2) Only on the school's local network: no account, but no camera and only inside the school.
Choice [1/2]:

Type 2 and press Enter.

The answer must be the one chosen in the step Prepare the network. Changing one's mind later is possible, without losing the data: see Switch from the local network to Tailscale.

What computer it is

What kind of computer is this?
  1) micro: a very small computer, with 512 MB of memory
  2) small: a Raspberry Pi 4 with 2 GB and an SD card
  3) medium: an older PC with a hard disk
  4) large: a PC with an SSD
Choice [small, suggested for this computer]:

The profile governs how much memory and how much work BiblioViva asks of the computer: one too high for a small computer makes it slow (see the glossary). The program looks at the memory and at the type of disk and proposes the suitable profile, written between the square brackets.

Press Enter to accept the proposal. The profile can be changed later from BiblioViva.

With the local network there is no other question: the program goes straight to the installation. If the computer does not have the service that gives it the name biblioviva.local (avahi-daemon), the program installs it by itself.

Wait for the installation

The program then writes the phases of the work, each preceded by ==, and between one and the next the lines of the programs it calls.

== Preparing the folder /home/<user>/biblioviva

== Installing avahi-daemon, which makes the computer reachable as biblioviva.local

== Downloading BiblioViva (the first time it can take a few minutes)

== Starting BiblioViva

== Waiting for BiblioViva to answer (up to 180 seconds)

The avahi-daemon line appears only if the service is missing.

Wait. The download is the longest phase, especially on a Raspberry Pi with an SD card. The terminal writes lines with percentages and labels ("Pulling", "Download complete"): they are normal.
Do not close the terminal and do not switch the computer off until the program has written the address.

Note the address

At the end the program writes that BiblioViva is ready and the address to open.

BiblioViva is ready. Open in the browser:

    http://biblioviva.local:8080
    http://192.168.1.50:8080

(from a computer on the school network; if the name does not work, use the numeric address)

Write down the two addresses the program writes: the one with the name and the numeric one (the second is absent if the program cannot read the computer's address). The numeric address changes from school to school: it is the one the router reserved in the step Prepare the network. They are needed in the step First run.
If Docker was installed during this run, close the terminal and connect again as in the step Connect to the computer.

Check before going on

The program finished with no error messages and the last part it wrote begins with "BiblioViva is ready.".
Under that sentence an address appears, and it is written down.
The following command, given in the terminal, lists BiblioViva's containers with the status Up (or running):
```
cd ~/biblioviva && docker compose ps
```
If the command answers "permission denied" about Docker, the terminal has not been reopened since the installation of Docker: close it and connect again, or repeat the command with sudo in front.

When one of the points is missing, see "Possible problems". Running the command of the first point of the procedure again does no harm: the program recognises the installation already made and updates it without asking questions (see Update BiblioViva).

Possible problems

The program writes the error message and stops. After removing the cause, repeat the command of the first step of the procedure.

"This program runs on Linux only (Raspberry Pi OS, Debian or Ubuntu).": the command was pasted on the wrong computer, for example one's own work computer. Paste it into the BiblioViva terminal, opened in the step Connect to the computer.
"The system is 32-bit (…): BiblioViva needs a 64-bit system. On a Raspberry Pi, install Raspberry Pi OS (64-bit).": the microSD card holds a 32-bit system. Write it again with Raspberry Pi OS Lite (64-bit) as in the step Prepare the computer; the command cannot work on a 32-bit system.
"System …: this program is tested on Raspberry Pi OS, Debian and Ubuntu. Going on…": a warning, not an error. The computer has another Linux distribution (for example Fedora) and the program goes on; if the installation stops, see the technical page Deployment notes (technical).
"The sudo command is not available: run the program as an administrator or install sudo.": the computer does not have sudo. Install it following the distribution's instructions, or connect as the root user and repeat the command.
"Docker was not installed: the program stops. Install it and run the program again.": n was answered to the question, or the installation of Docker failed (for example for lack of internet). Repeat the command and answer Y; if the error stays, install Docker with the official guide and repeat the command.
"An answer is missing and there is no terminal to read it from: give …": the program is not in a window where one can type (for example the command was launched from another program). Open the terminal as in the step Connect to the computer and repeat the command. Alternatively the answers are given with the options --network tailscale or --network lan, --profile micro, --profile small, --profile medium or --profile large, --key <key> for the Tailscale key and --yes to install Docker without questions, for example:
```
curl -fsSL https://raw.githubusercontent.com/itotm/biblioviva/main/setup.sh | bash -s -- --lang en --network lan --profile small
```
"Invalid answer.": the answer is not among those allowed. Type one of the digits listed.
"Cannot download …: check the internet connection.": the computer cannot download a BiblioViva file. Check that the cable or Wi-Fi work (for example with ping -c 3 raspberrypi.com), then repeat the command.
"BiblioViva does not answer yet. See the log with: cd … && docker compose logs": BiblioViva was started but does not answer after 180 seconds. On a slow computer the start can take longer: wait two minutes and repeat the command, which resumes from where it got to. If the message repeats, give the command the program suggests and read the last lines; if Docker has just been installed and the command answers "permission denied", put sudo in front.
```
cd ~/biblioviva && docker compose logs
```
Docker writes "port is already allocated" and the program stops: another program occupies port 8080. Ask whoever manages the computer to free it, or write another number after LAN_PORT= in the file ~/biblioviva/.env and repeat the command: the addresses change accordingly.
The address with the name (biblioviva.local) does not open from the other computers: use the numeric address the program wrote. The check from the desk computer is in the step Connect the devices.