Optimize Documentation: Install BookStack with Nginx on Ubuntu 20.04

BookStack is a versatile and user-friendly platform for organizing and storing information. It can be used as a wiki, documentation website, or note-taking application. Built on the Laravel PHP framework and utilizing MySQL for data storage, BookStack offers features such as a WYSIWYG or Markdown editor, multi-factor authentication, dark mode, and multilingual support. In this tutorial, we will guide you through the process of installing BookStack on a Ubuntu 20.04 server, using Nginx as the web server.

Prerequisites

Before we begin, make sure you have the following:

• A server running Ubuntu 20.04
• A Fully Qualified Domain Name (FQDN) pointing to the server
• A non-root user with sudo privileges
• PHP version 7.3 or greater
• MySQL version 5.6 or greater, or MariaDB version 10.0 or greater
• Git and Composer installed

Now that we have everything we need, let’s get started with the installation process.

Step 1: Configure Firewall

First, we need to configure the firewall to allow incoming connections. Ubuntu comes with a firewall called UFW (Uncomplicated Firewall) by default. Check if the firewall is running by executing the following command:

sudo ufw status

If the firewall is inactive, enable it by running:

sudo ufw enable

Next, allow SSH, HTTP, and HTTPS traffic through the firewall:

sudo ufw allow OpenSSH
sudo ufw allow 80
sudo ufw allow 443

Verify the firewall rules by running:

sudo ufw status

Step 2: Install Git

Git is a version control system that is used to download and update BookStack. Install Git by running the following command:

sudo apt install git

Verify the installation by checking the Git version:

git --version

Step 3: Install PHP and Extensions

BookStack relies on PHP, so we need to install PHP and its extensions. By default, Ubuntu ships with an outdated version of PHP. We will use Ondrej’s PHP repository to install PHP 7.4, which is the recommended version for BookStack. Add the repository by running:

sudo add-apt-repository ppa:ondrej/php

Next, install PHP and the required extensions:

sudo apt install php7.4-fpm php7.4-mbstring php7.4-gd php7.4-xml unzip php7.4-bcmath php7.4-curl php7.4-mysql

Verify the installation by checking the PHP version:

php --version

Step 4: Install and Configure MariaDB

BookStack requires a database to store its data. We will use MariaDB, which is a drop-in replacement for MySQL. By default, Ubuntu ships with an older version of MariaDB, so we need to add the official MariaDB repository to install the latest version. Run the following commands to add the repository and install MariaDB:

curl -LsS -O https://downloads.mariadb.com/MariaDB/mariadb_repo_setup
sudo bash mariadb_repo_setup --mariadb-server-version=10.6
sudo apt install mariadb-server

After the installation, secure the MariaDB installation by running:

sudo mysql_secure_installation

Follow the prompts to set the root password, remove anonymous users, disallow remote root login, remove the test database, and reload the privilege tables.

Next, create a new database and user for BookStack:

sudo mysql

In the MySQL shell, run the following commands to create the database and user:

CREATE DATABASE bookstack;
CREATE USER 'bookstackuser'@'localhost' IDENTIFIED BY 'bookstackpassword';
GRANT ALL PRIVILEGES ON bookstack.* TO 'bookstackuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Replace ‘bookstackuser’ and ‘bookstackpassword’ with your desired username and password.

Step 5: Install Composer

Composer is a dependency management tool for PHP, and it is required by Laravel, the framework on which BookStack is built. Download the Composer installer script by running:

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

Verify the installer by running the following commands:

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;"

If the installer is verified, proceed with the installation:

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

Verify the installation by checking the Composer version:

composer --version

Step 6: Download and Install BookStack

Create a directory for the BookStack installation:

sudo mkdir -p /var/www/bookstack

Change the ownership of the directory to the current user:

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

Clone the BookStack repository into the directory:

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

Install the required dependencies using Composer:

composer install --no-dev

Copy the example environment file and edit it:

cp.env.example.env
sudo nano.env

Update the following lines in the .env file to match your configuration:

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

Save the file and exit the editor.

Generate a unique application key:

php artisan key:generate

Update the database schema:

php artisan migrate

Clear the cache:

php artisan cache:clear
php artisan config:clear
php artisan view:clear

Step 7: Install Let’s Encrypt SSL

To secure your BookStack installation with an SSL certificate, we will use Let’s Encrypt and their Certbot tool. Install Snap, the package installer for Snapd:

sudo apt install snapd

Ensure that Snapd is up to date:

sudo snap install core
sudo snap refresh core

Install Certbot:

sudo snap install --classic certbot

Create a symbolic link to the Certbot command:

sudo ln -s /snap/bin/certbot /usr/bin/certbot

Generate the SSL certificate:

sudo certbot certonly --standalone --agree-tos --preferred-challenges http -m test@example.com -d example.com

This command will download the SSL certificate to the /etc/letsencrypt/live/example.com directory on your server.

Generate a Diffie-Hellman group certificate:

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

Create a challenge web root directory for Let’s Encrypt auto-renewal:

sudo mkdir -p /var/lib/letsencrypt

Create a cron job to renew the SSL certificate automatically. Open the renew script:

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

Add the following code to the file:

#!/bin/sh

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

Save the file and exit the editor. Make the script executable:

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

Step 8: Install and Configure Nginx

Ubuntu ships with an older version of Nginx, so we will install the latest version from the official Nginx repository. Add the repository:

echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg arch=amd64] \
http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" \
    | sudo tee /etc/apt/sources.list.d/nginx.list

Install Nginx:

sudo apt update
sudo apt install nginx

Enable the Nginx service:

sudo systemctl enable nginx

Step 9: Configure PHP-FPM

To ensure that PHP-FPM works correctly with Nginx, we need to make a few configuration changes. Open the PHP-FPM configuration file:

sudo nano /etc/php/7.4/fpm/pool.d/www.conf

Change the following lines to set the user and group to nginx:

user = nginx
group = nginx

Save the file and exit the editor.

Find the following lines in the Nginx configuration file:

listen.owner = www-data
listen.group = www-data

Change them to:

listen.owner = nginx
listen.group = nginx

Save the file and exit the editor.

Restart the PHP-FPM service:

sudo systemctl restart php7.4-fpm

Step 10: Configure Nginx

Create a new Nginx configuration file for BookStack:

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

Add the following code to 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/php7.4-fpm.sock;
    }
}

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

Replace example.com with your domain name.

Save the file and exit the editor.

Open the main Nginx configuration file:

sudo nano /etc/nginx/nginx.conf

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

server_names_hash_bucket_size 64;

Save the file and exit the editor.

Verify the Nginx configuration:

sudo nginx -t

If there are no syntax errors, start the Nginx service:

sudo systemctl start nginx

Step 11: Run BookStack

Your BookStack installation is now ready to use. Open your web browser and visit https://example.com (replace example.com with your domain name). You should see the BookStack login page.

Log in using the default administrator account:

• Email: test@example.com
• Password: password

Once logged in, go to Settings > Users and click on the “Add New User” button. Fill in the user details, checkmark the “Admin” box under User Roles, and uncheck the “Send user invite email” option. Select a strong password and click “Save” when finished.

Next, click on the default “Admin” user and delete it by clicking the “Delete User” button. Transfer the ownership of the Admin user to the newly created user by selecting it from the dropdown menu before deleting it. Click “Confirm” to finish. You will be automatically logged out and will need to log back in with the newly created user.

Step 12: Backup and Restore BookStack

It is important to regularly backup your BookStack installation to protect your data. To back up the database, use the mysqldump tool:

sudo mysqldump -u bookstackuser bookstack > bookstack.backup.sql

To back up the files, create a compressed archive of the following files and folders:

• .env – file containing important configuration
• public/uploads – folder containing uploaded images
• storage/uploads – folder containing uploaded page attachments

sudo tar -czvf bookstack-files-backup.tar.gz.envpublic/uploads storage/uploads

To restore the BookStack installation from a backup, follow these steps:

1. Restore the database:

sudo mysql -u bookstackuser bookstack < bookstack.backup.sql

Note: If you are restoring to a new version of BookStack, you may need to run the php artisan migrate command to update the database schema.

1. Restore the compressed files:

sudo tar -xvzf bookstack-files-backup.tar.gz

1. Update file permissions:

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

Conclusion

Congratulations! You have successfully installed BookStack with Nginx on your Ubuntu 20.04 server. You can now start organizing and storing information using this powerful platform. By following the steps outlined in this tutorial, you have created a secure and efficient BookStack installation. If you have any questions or need assistance, feel free to reach out to our team at Shape.host. We provide reliable Linux SSD VPS hosting services to empower businesses with scalable and secure cloud hosting solutions. Visit us at Shape.host for more information.