How to Install BookStack on Ubuntu 16.04 LTS

BookStack is an open source platform to create documentation/wiki content for your project. It has been written in the PHP programming language with the Laravel web framework. Basically, your project documentation/wiki gets stored on BookStack as a ‘Book’, followed by ‘Chapter’ and ‘Pages’. And it makes it easier for you to create and read the documentation as a Book, based on Chapter and Pages.

In this tutorial, I will show you step-by-step how to install and configure BookStack on Ubuntu 16.04 under the LEMP (Linux, Nginx, PHP-FPM, MySQL/MariaDB) stack. This tutorial will cover details including how to install the PHP Composer and create the MySQL database manually using the command line.

Prerequisites

• Ubuntu 16.04
• Root privileges

What we will do

1. Update Repository and Upgrade System
2. Install Nginx on Ubuntu 16.04
3. Install and Configure PHP-FPM
4. Install and Configure MariaDB Database
5. Install PHP Composer
6. Install and Configure BookStack
7. Configure Nginx Virtual Host for BookStack
8. Testing

Step 1 – Update and Upgrade Ubuntu

Before installing any packages for BookStack installation, make sure your Ubuntu repository and system is up to date.

If not, you can update the Ubuntu repository and upgrade the system using commands below.

sudo apt update
sudo apt upgrade

Step 2 – Install Nginx on Ubuntu 16.04

In this tutorial, we will run the ‘BookStack’ platform under the LEMP stack, and we will install the Nginx web server from the Ubuntu repository.

Install Nginx web server on Ubuntu using the apt command below.

sudo apt install nginx -y

After the installation is complete, start the service and enable it to launch everytime at system boot.

systemctl start nginx
systemctl enable nginx

Now check the nginx service status and the open port on the system, make sure you get the HTTP port 80 on the list.

Run commands below.

systemctl status nginx
netstat -plntu

Following is the result.

The Nginx web server is installed on the Ubuntu 16.04 server.

Step 3 – Install and Configure PHP-FPM

In this step, we will install and configure PHP-FPM 7.0. We will install PHP and PHP-FPM with some extensions that are needed by ‘BookStack’, including PDO, Tokenizer, GD, Tidy, MBString, and OpenSSL.

Install PHP and PHP-FPM with all required extensions by running the apt command below.

sudo apt install php7.0-fpm php7.0-mcrypt php7.0-curl php7.0-cli php7.0-mysql php7.0-gd php7.0-xsl php7.0-json php7.0-intl php-pear php7.0-dev php7.0-common php7.0-mbstring php7.0-tidy php7.0-zip php-soap libcurl3 curl -y

After the installation is complete, we need to configure the ‘php.ini’ configuration files for ‘php fpm’ and ‘php cli’.

Edit the ‘php.ini’ file for ‘fpm’ configuration using vim.

vim /etc/php/7.0/fpm/php.ini

Uncomment the ‘cgi.fix_pathinfo’ line and change the value to ‘0’.

cgi.fix_pathinfo=0

Save and exit.

Edit the ‘php.ini’ file for ‘cli’ configuration using vim.

vim /etc/php/7.0/cli/php.ini

Uncomment the ‘cgi.fix_pathinfo’ line and change the value to ‘0’.

cgi.fix_pathinfo=0

Save and exit.

Now start the PHP-FPM service and enable it to launch everytime at system boot.

systemctl start php7.0-fpm
systemctl enable php7.0-fpm

On Ubuntu system, PHP-FPM will run under the ‘sock’ file – check it using the netstat command below.

netstat -pl | grep fpm

And you will get the result as below.

PHP and PHP-FPM with all required extensions have been installed.

Step 4 – Install and Configure MariaDB Database

BookStack only offers supports for the MySQL database, and runs only under MySQL version >= 5.6. For this tutorial, we will be using the MariaDB latest version that can be installed from the Ubuntu repository.

Run the following apt command to install the MariaDB database.

sudo apt install mariadb-server mariadb-client -y

After the installation is complete, start the service and enable it to launch everytime at system boot.

systemctl start mysql
systemctl enable mysql

Now we need to configure the ‘root’ password for the database.

Run the following command to set up the ‘root’ database password.

mysql_secure_installation

And you will be asked for the new MySQL root password – type your password for the root user and press Enter. For others, just type ‘Y’ to yes and Enter again.

Set root password? [Y/n] Y
Remove anonymous users? [Y/n] Y
Disallow root login remotely? [Y/n] Y
Remove test database and access to it? [Y/n] Y
Reload privilege tables now? [Y/n] Y

The MySQL root password has now been set up.

Next, we need to create a new database for BookStack installation.

We will create a new database named ‘bookstackdb‘ with user ‘bookstak‘ and the password ‘[email protected]‘.

Login to the MySQL shell as the root user.

mysql -u root -p

Now run all MySQL queries below.

create database bookstackdb;
create user [email protected] identified by ‘[email protected]‘;
grant all privileges on bookstackdb.* to [email protected] identified by ‘[email protected]‘;
flush privileges;
exit;

MySQL/MariaDB has been installed on the Ubuntu system, and the database for ‘BookStack’ installation has been created.

Step 5 – Install PHP Composer

The Composer is a dependency manager for PHP. It allows you to manage PHP dependencies that you need for your project. In this step, we will install the Composer using the installer script. The Composer will be used for downloading all PHP libraries that are needed by the ‘BookStack’.

Go to the home directory and download the installer using curl.

cd ~/
curl -sS https://getcomposer.org/installer | php

And you will get the ‘composer.phar’ file in your home directory, move the file to the ‘/usr/bin’ directory, and run the ‘composer’ command as below.

mv composer.phar /usr/bin/composer
composer -v

You will get the composer version that’s installed on your system.

The PHP Composer is now installed on Ubuntu 16.04.

Step 6 – Install BookStack

In this step, we will install BookStack under the ‘/var/www’ directory, which will be the root application directory.

Goto the ‘/var/www’ directory and clone the ‘BookStack’ source code using the git command.

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

Go to the ‘BookStack/’ directory and install all PHP dependencies using the composer command as shown below.

cd BookStack/
composer install

Make sure you get no error and when it’s complete,  you will see the result as below.

Now copy the environment configuration file ‘.env.example’ and edit it using vim.

cp .env.example .env
vim .env

On the database details line, change everything with your database info, as shown below.

# Database details
DB_HOST=localhost
DB_DATABASE=bookstackdb
DB_USERNAME=bookstack
[email protected]

Save and exit.

And change the owner of the ‘BookStack’ directory to the ‘www-data’ user and group.

chown -R www-data:www-data /var/www/BookStack

Next, we need to generate the unique application key for BookStack and update the database schema using PHP artisan commands.

On the root application directory ‘/var/www/BookStack’, run commands as shown below.

php artisan key:generate
php artisan migrate

You will be asked for confirmation, type ‘yes’ and press Enter.

Wait for the command to generate the secret key and import the database scheme.

BookStack has now been installed on Ubuntu 16.04, the secret unique key application has been generated, and the database scheme for BookStack has been updated.

Step 7 – Configure Nginx Virtual Host for BookStack

In this step, we will configure the nginx virtual host for BookStack. We will be using ‘book.hakase-labs.co’ as a domain name for our BookStack URL.

Goto the ‘/etc/nginx’ directory and create a new virtual host file ‘bookstack’ under ‘sites-available’ directory using the vim editor.

cd /etc/nginx/
vim sites-available/bookstack

Paste the configuration below.

server {
  listen 80;
  server_name book.hakase-labs.co;
  root /var/www/BookStack/public;
  access_log  /var/log/nginx/bookstack_access.log;
  error_log  /var/log/nginx/bookstack_error.log;
  client_max_body_size 1G;
  fastcgi_buffers 64 4K;
  index  index.php;
  location / {
    try_files $uri $uri/ /index.php?$query_string;
  }
  location ~ ^/(?:\.htaccess|data|config|db_structure\.xml|README) {
    deny all;
  }
  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.0-fpm.sock;
  }
  location ~* \.(?:jpg|jpeg|gif|bmp|ico|png|css|js|swf)$ {
    expires 30d;
    access_log off;
  }
}

Save and exit.

Now activate the virtual host and test the configuration.

ln -s /etc/nginx/sites-available/bookstack /etc/nginx/sites-enabled/
nginx -t

Make sure you get no error as shown below.

Now restart the Nginx service.

systemctl restart nginx

The Nginx virtual host for BookStack has been added and activated.

Step 8 – Testing

Open your web browser and type the BookStack URL on the address bar, mine is http://book.hakase-labs.co/

And you will be redirected to the ‘login/’ page as shown below.

Type default admin user ‘[email protected]‘ with password ‘password‘, then press ‘Login‘ button.

And you will get the BookStack user Dashboard.

Click on the ‘Settings’ menu and you will get the settings page.

Now click the ‘Users’ menu and then click the ‘Admin’ user. Change the default email with your email address and the password with your own secret password.

Then click the ‘Save’ button.

With this, the BookStack installation with LEMP (Linux, Nginx, MariaDB, and PHP-FPM) stack on Ubuntu 16.04 has been completed successfully.

Reference