How to Install BookStack on Rocky Linux

BookStack is a self-hosted, open source and easy-to-use platform for organizing and storing information. It can be used for various purposes, such as a wiki, documentation website and note-taking application, to name a few. It was developed with the Laravel PHP framework and uses MySQL to store the data. For editing, you can choose between a WYSIWYG and a Markdown editor. It supports multi-factor authentication and dark mode and is multilingual.

In this tutorial you will learn how to install BookStack on a Rocky Linux 8 based server.

Prerequisites

A server running Rocky Linux 8
A Fully Qualified Domain Name (FQDN) pointing to the server.
A non-root user with sudo privileges.
PHP version 7.3 or higher.
MySQL>=5.6 and MariaDB>=10.0
Git and Composer.

Step 1 – Configure firewall

The first step is to configure the firewall. Rocky Linux uses the Firewalld firewall. Check the status of the firewall.

$ sudo firewall-cmd --state
running

The firewall works with different zones and the public zone is the default zone we will use. List all services and ports that are active on the firewall.

$ sudo firewall-cmd --permanent --list-services

You should see the following output.

cockpit dhcpv6-client ssh

Allow HTTP and HTTPS ports.

$ sudo firewall-cmd --permanent --add-service=http
$ sudo firewall-cmd --permanent --add-service=https

Check the status of the firewall again.

$ sudo firewall-cmd --permanent --list-services

You should see a similar output.

cockpit dhcpv6-client http https ssh

Reload the firewall to enable the changes.

$ sudo firewall-cmd --reload

Step 2 – Install Git

The first step is to install Git. It is required to download and update BookStack. Run the following command to install Git.

$ sudo dnf install git

Verify the installation.

$ git --version
git version 2.27.0

Step 3 – Install PHP and extensions

Since BookStack relies on PHP, you need to install PHP and its extensions.

The Rocky Linux AppStream repository ships with PHP. To list all available PHP versions, run the following command.

$ sudo dnf module list php
Last metadata expiration check: 0:04:24 ago on Sat 06 Nov 2021 11:01:33 AM UTC.
Rocky Linux 8 - AppStream
Name                Stream                 Profiles                                 Summary
php                 7.2 [d]                common [d], devel, minimal               PHP scripting language
php                 7.3                    common [d], devel, minimal               PHP scripting language
php                 7.4                    common [d], devel, minimal               PHP scripting language

Hint: [d]efault, [e]nabled, [x]disabled, [i]nstalled

The default version is set to 10.3. However, you can enable a different version with the following command.

$ sudo dnf module enable php:7.4

The PHP version that is available in this way is not the latest version. To install the latest version, you need to install the Remi repository. For our tutorial, we will use the version provided by the operating system.

Next, install PHP and the extensions required by BookStack.

$ sudo dnf install php-fpm php-mbstring php-gd php-xml unzip php-bcmath php-curl php-mysqlnd php-cli php-json

Verify the installation.

$ php --version
PHP 7.4.6 (cli) (built: May 12 2020 08:09:15) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies

Step 4 – Install and configure MariaDB

The Rocky Linux AppStream repository comes with MariaDB. To list all available versions of MariaDB, run the following command.

$ sudo dnf module list mariadb
Last metadata expiration check: 1:15:26 ago on Thu 21 Oct 2021 10:20:01 AM UTC.
Rocky Linux 8 - AppStream
Name                          Stream                         Profiles                                         Summary
mariadb                       10.3 [d]                       client, galera, server [d]                       MariaDB Module
mariadb                       10.5                           client, galera, server [d]                       MariaDB Module

Hint: [d]efault, [e]nabled, [x]disabled, [i]nstalled

The default version is set to 10.3. However, you can activate the latest version with the following command.

$ sudo dnf module enable mariadb:10.5

Run the following command to install the MariaDB server.

$ sudo dnf install mariadb-server

Activate and start the MariaDB service.

$ sudo systemctl enable --now mariadb

Save the MariaDB installation.

$ sudo mysql_secure_installation

You will see several prompts. Answer them as follows.

Enter current password for root (enter for none): Press Enter
Switch to unix_socket authentication [Y/n] Type y
Change the root password? [Y/n] Type n
Remove anonymous users? [Y/n] Type y
Disallow root login remotely? [Y/n] Type y
Remove test database and access to it? [Y/n] Type y
Reload privilege tables now? [Y/n] Type y

Connect to the MariaDB shell with the following command.

$ sudo mysql

Create a new database for Bookstack.

$ create database bookstack;

Create a new database user.

$ CREATE USER 'bookstackuser'@'localhost' identified by 'bookstackpassword';

Choose a secure password.

Give the user permissions to the database.

$ grant ALL on `bookstack`.* to 'bookstackuser'@'localhost';

Exit the MySQL shell.

$ exit

Step 5 – Install Composer

Composer is a dependency management tool for PHP and is required by Laravel, on which BookStack is based.

Download the Composer installation script.

$ curl -sS https://getcomposer.org/installer -o composer-setup.php

Run the following commands to verify the installer.

$ HASH=`curl -sS https://composer.github.io/installer.sig`
$ echo $HASH
$ php -r "if (hash_file('SHA384', 'composer-setup.php') === '$HASH') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"

The above commands will capture the installer’s hash value and match it with your downloaded script. If the installer is safe to run, you should see the following output.

Installer verified

Install Composer.

$ sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer

Verify the installation by checking the version.

$ composer --version
Composer version 2.1.11 2021-11-02 12:10:25

Step 6 – Download and install BookStack

Create the root folder for the BookStack app.

$ sudo mkdir -p /var/www/bookstack

Change the ownership of the /var/www/bookstack directory to the currently logged in user.

$ sudo chown -R $USER:$USER /var/www/bookstack

Clone the release branch of the BookStack github repository to the newly created folder.

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

Don’t forget the dot at the end of the clone command. It will ensure that all files are downloaded to the current directory instead of creating a new one.

Start the Composer installer from the /var/www/bookstack directory.

$ composer install --no-dev

Copy the .env.example file to .env to save environment variables for the installation.

$ cp .env.example .env

Open the file for editing.

$ sudo nano .env

Enter the application URL and database details. If you want to use the email functions, enter the SMTP data or delete it from the file.

APP_URL=https://example.com
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstackuser
DB_PASSWORD=bookstackpassword

Save the file by pressing Ctrl X and typing Y when prompted. There are many more settings you can make. To learn more, open the file .env.example.complete and copy the settings you need into your file .env.

Create a unique application key. This value is automatically entered in the .env file. Enter yes to continue with the command.

$ php artisan key:generate
**************************************
*     Application In Production!     *
**************************************

 Do you really wish to run this command? (yes/no) [no]:
 > yes

Application key set successfully.

Update the database.

$ php artisan migrate
**************************************
*     Application In Production!     *
**************************************

 Do you really wish to run this command? (yes/no) [no]:
 > yes
Migration table created successfully.
Migrating: 2014_10_12_000000_create_users_table
Migrated:  2014_10_12_000000_create_users_table (0.12 seconds)
.......

Change the ownership of the directory to the user nginx, so that the web server can access and write to the folder.

$ sudo chown -R nginx:nginx /var/www/bookstack

Step 7 – Install Let’s Encrypt SSL

To install an SSL certificate with Let’s Encrypt, we need to install the Certbot tool.

First, you need to download and install the EPEL repository.

$ sudo dnf install epel-release

Execute the following commands to install Certbot.

$ sudo dnf install certbot

Create the SSL certificate.

$ sudo certbot certonly --standalone --agree-tos --preferred-challenges http -m [email protected] -d example.com

The above command will download a certificate to the /etc/letsencrypt/live/bookstack.example.com directory on your server.

Create a Diffie-Hellman group certificate.

$ sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048

Create a challenge web root directory for automatic renewal of Let’s Encrypt.

$ sudo mkdir -p /var/lib/letsencrypt

Create a cron job to renew the SSL certificate. It will run every day to check the certificate and renew it if needed. To do this, first create the file /etc/cron.daily/certbot-renew and open it for editing.

$ sudo nano /etc/cron.daily/certbot-renew

Paste the following code.

#!/bin/sh
certbot renew --cert-name bookstack.example.com --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"

Save the file by pressing Ctrl X and typing Y when prompted.

Change the permissions on the task file to make it executable.

$ sudo chmod  x /etc/cron.daily/certbot-renew

Step 8 – Install and configure Nginx

Rocky Linux 8 ships with an older version of Nginx. To install the latest version, you will need to download the official Nginx repository.

Create and open the file /etc/yum.repos.d/nginx.repo to create the official Nginx repository.

$ sudo nano /etc/yum.repos.d/nginx.repo

Paste the following code into the file.

[nginx-stable]
name=nginx stable repo
baseurl=http://nginx.org/packages/centos/$releasever/$basearch/
gpgcheck=1
enabled=1
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true

[nginx-mainline]
name=nginx mainline repo
baseurl=http://nginx.org/packages/mainline/centos/$releasever/$basearch/
gpgcheck=1
enabled=0
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true

Save the file by pressing Ctrl X and typing Y when prompted.

Install Nginx.

$ sudo dnf install nginx

Verify the installation.

$ nginx -v
nginx version: nginx/1.20.1

Enable the Nginx service.

$ sudo systemctl enable nginx

Configure PHP-FPM

Open the file /etc/php-fpm.d/www.conf.

$ sudo nano /etc/php-fpm.d/www.conf

We need to set the Unix user/group of the PHP processes to nginx. Find the lines user=www-data and group=www-data in the file and change them to nginx.

...
; Unix user/group of processes
; Note: The user is mandatory. If the group is not set, the default user's group
;       will be used.
user = nginx
group = nginx
...

Save the file by pressing Ctrl X and typing Y when prompted.

Restart the PHP-fpm process.

$ sudo systemctl restart php-fpm

Configure Nginx

Create and open the file /etc/nginx/conf.d/bookstack.conf for editing.

$ sudo nano /etc/nginx/conf.d/bookstack.conf

Paste the following code into the file.

server {
    listen       443 ssl http2;
    listen       [::]:443 ssl http2;
    server_name  bookstack.example.com;

    access_log  /var/log/nginx/bookstack.access.log;
    error_log   /var/log/nginx/bookstack.error.log;
    
    ssl_certificate      /etc/letsencrypt/live/bookstack.example.com/fullchain.pem;
    ssl_certificate_key  /etc/letsencrypt/live/bookstack.example.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/bookstack.example.com/chain.pem;

    ssl_session_timeout  5m;
    ssl_session_cache shared:MozSSL:10m;
    ssl_session_tickets off;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
    ssl_ecdh_curve X25519:prime256v1:secp384r1:secp521r1;
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;

    root /var/www/bookstack/public;
    index index.php index.html;

    location / {
      try_files $uri $uri/ /index.php?$query_string;
    }
  
    location ~ .php$ {
      fastcgi_split_path_info ^(. .php)(/. )$;
      include fastcgi_params;
      fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
      fastcgi_param PATH_INFO $fastcgi_path_info;
      fastcgi_pass unix:/run/php-fpm/www.sock;
    }
}

# enforce HTTPS
server {
    listen       80;
    listen       [::]:80;
    server_name  bookstack.example.com;
    return 301   https://$host$request_uri;
}

Save the file by pressing Ctrl X and typing Y when prompted.

Open the file /etc/nginx/nginx.conf and edit it.

$ sudo nano /etc/nginx/nginx.conf

Insert the following line before the line include /etc/nginx/conf.d/*.conf;.

server_names_hash_bucket_size  64;

Save the file by pressing Ctrl X and typing Y when prompted. Check Nginx again.

Check the syntax of the Nginx configuration file.

$ sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Finally, start the Nginx service to activate the new configuration.

$ sudo systemctl start nginx

Step 9 – Run BookStack

Your bookstack is now ready for use. Open the URL https://bookstack.example.com in your browser and you will get the login page.