Bookstack

Introduction

We wanted an alterative notebook application for the evolution of the Home Lab and we have decided that we will try Bookstack. As we already a webserver setup already and the install was not going to need much in the way of resources like nextcloud or new libs we have added it as another vhost on Plum instead of another Virtual Machine. One the advantages of using an existing webserver are that the supporting services that are already installed and we can use the same SSL configuration files and Postfix as are already setup on Plum.

Installation of Bookstack

The installation will be divided in to steps.

• Create the database user
• Configure the Apache Virtual Host definition
• Setup the directories in /var/www and download the application files
• Setup the reverse proxy definition for Nginx on Raisin

MySQL user

The Bookstack application runs from MySQL so it will need a Database and a user. To create the database and user ssh to mandarin then login to mysql as root

mysql -u root -p

next create the database and user with

CREATE DATABASE bookstack;
CREATE USER 'bookstack_user'@'192.168.100.22' IDENTIFIED BY 'Somelongpassword';
GRANT ALL PRIVILEGES ON bookstack.* TO 'bookstack_user'@'192.168.100.22';
FLUSH PRIVILEGES;

Be careful to make sure the password is long enough and has numbers, upper & lower case letters. Note we have set MySQL to use the secure settings so it would be easiest to have the password manager set a long random password and then storing it in the password manager.

Apache Virtual Host Definition

We will need a definition in Apache so that we can access the application. We will use the Lets encrypt SSL certs. First we will need to create the file

sudo nano /etc/apache2/sites-available/bookstack.conf

Copy and paste the following to the file

    ServerName notes.seaoffate.net
    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]
</VirtualHost>

<VirtualHost *:443>
    ServerName notes.seaoffate.net
    DocumentRoot /var/www/bookstack/public_html

    <Directory /var/www/bookstack/public_html>
        Options FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    #new letsencrypt cert
    SSLEngine on
    SSLCertificateFile    /etc/nginx/ssl/seaoffate.net/fullchain.pem
    SSLCertificateKeyFile /etc/nginx/ssl/seaoffate.net/privkey.pem

    # Security Headers
    Header always set X-Frame-Options "SAMEORIGIN"
    Header always set X-Content-Type-Options "nosniff"
</VirtualHost>

Note The entry for port 80 will never actually be used outside of the LAN because it is dropped at the edge router and pfsense and not forwarded on by the reverse proxy. Save & close the bookstack.conf enable the website

sudo a2ensite bookstack.conf

restart Apache

sudo systemctl restart apache2

check the status of Apache

sudo systemctl status apache2

If it fails to start check try the following although with the other applications like wikimedia they are likely already installed

sudo a2enmod headers
sudo a2enmod rewrite

I may refuse to start if the conf cannot find the DocumentRoot if so proceed to the next step and create the directory for it and then come back to the systemctl restart apache2 command.

If we want to test the application from within the LAN we will need to add the DNS name to our internal DNS server CTNS1 so ssh to ctns1 and run the bash script to add notes to Plum's IP address

./add_combined_dns.sh notes 192.168.100.22

As we are using the Letsencrypt SSL certs we should have no security warnings from the browser

Install Bookstack Application

we need to check the prerequisites are installed although they were most likely installed with the other web applications it would be best to check

sudo apt update
sudo apt install php-fpm php-curl php-mbstring php-ldap php-tidy php-xml php-zip php-gd php-mysql git curl

Next download the latest release of bookstack

cd /var/www
sudo git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch bookstack
cd bookstack

Use Composer to pull in the Laravel framework and other required libraries

composer install --no-dev

Note not running it as sudo Copy the template environment file and update it with your specific details for Plum and our remote MySQL host.

cp .env.example .env
nano .env

Required Edits in .env:

• APP_URL: http://notes.seaoffate.net
• DB_HOST: [IP_OF_YOUR_DATABASE_HOST]
• DB_DATABASE: bookstack
• DB_USERNAME: bookstack_user
• DB_PASSWORD: your_secure_password

Generate the unique encryption key for your install and then run the migrations to build the tables on your remote database.

php artisan key:generate
php artisan migrate

Ensure Apache can write to the necessary directories for file uploads and caching.

sudo chown -R www-data:www-data storage bootstrap/cache public/uploads
sudo chmod -R 775 storage bootstrap/cache public/uploads

Reverse Proxy Definition

The application will need to be forwarded by the Nginx reverse proxy on Raisin so we need to ssh to raisin and add in an entry we will be adding it to one of the existing config files

sudo nano /etc/nginx/sites-enabled/new-media.conf

Scroll down to the bottom and paste in the following.

# bookstack notes on plum
server {
    listen 443 ssl;
    server_name notes.seaoffate.net;

    ssl_certificate /etc/letsencrypt/live/seaoffate.net/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/seaoffate.net/privkey.pem;

     location / {
        proxy_pass https://192.168.100.22; # Plum's IP
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Increase upload limit for when you upload network diagrams
        client_max_body_size 50M;
    }
}

Note If we were adding a new config file we should add it to /etc/nginx/sites-available and copy a shortcut to it at /etc/nginx/sites-enabled as it is poor practice to create the config files in the enabled directory. Once the file is saved and close we should test the new config with

sudo nginx -t

If the response is ok we can enable it with

sudo systemctl reload nginx

and as a final test to be sure everything is working

sudo systemctl status nginx

The final stage will be to log in to the DNS provider Cloudflare and add in a new DNS entry for notes.seaoffate.net

Final Testing

To check that the website works as expect use a mobile phone and browse to https://notes.seaoffate.net. There will be no books visible to start and a default user is defined so login and setup a new user

• Default Email: [email protected]
• Default Password: password

Once logged in Proceed to users and add new user. From the add new user page create a new user of type admin and set a password or have a password emailed to you save the user then logout the [email protected] user. Now login with the new user and go back to the users section and select the [email protected] user. Towards the bottom of the edit user page for [email protected] there is button to delete user, click it and a delete user page is displayed. In the box migrate ownership select the new user that was just created, (not sure if this is required but probably best to preserve anything from the default admin) then click confirm. From this poin on any bot attack on the default user will fail and unless the new admin/s email addresses are known bots will have to guess an email address and password. It would be better to create a new