How to Install BookStack Documentation Wiki on CentOS 7

BookStack is an open source platform to create documentation/wiki content for your project. It has been written in the PHP programming language and uses the Laravel web framework. Basically, your project documentation/wiki will be stored on BookStack as a ‘Book’, followed by ‘Chapter’ and ‘Pages’. 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 CentOS 7 under the LEMP (Linux, Nginx, PHP-FPM, MySQL/MariaDB) stack. This tutorial will cover topics including PHP Composer installation and creation of the MySQL database using the command line.

Prerequisites

• CentOS 7
• Root privileges

What we will do

1. Install EPEL Repository
2. Install Nginx
3. Install and Configure PHP-FPM
4. Install and Configure MySQL/MariaDB
5. Install PHP Composer
6. Install BookStack
7. Configure Nginx Virtual Host BookStack
8. Testing

Step 1 – Install EPEL Repository

Add the new third-party repository to the system. We need to add EPEL (Extra Packages for Enterprise Linux) repository to our CentOS 7 system, so we can install Nginx and other packages.

Install EPEL repository using the yum command below.

sudo yum -y install epel-release

Step 2 – Install Nginx on CentOS 7

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

Install Nginx web server using the yum command below.

sudo yum -y install nginx

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

systemctl start nginx
systemctl enable nginx

Now check it using the netstat command.

netstat -plntu

Make sure you get the port 80 on the list, and it’s used by the Nginx service.

The Nginx web server is now installed on the CentOS 7 system.

Additional: If you’re running firewalld on your system, add new HTTP service to the configuration by running the commands below.

firewall-cmd –add-service=http –permanent
firewall-cmd –reload

Step 3 – Install PHP and PHP-FPM

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

Before installing PHP and PHP-FPM, add new ‘webtatic’ repository to the CentOS 7 system using rpm command below.

rpm -Uvh https://mirror.webtatic.com/yum/el7/webtatic-release.rpm

Now install PHP and PHP-FPM with all extensions needed using the yum command in the following way.

sudo yum -y install php70w-fpm php70w-mcrypt php70w-curl php70w-cli php70w-mysql php70w-gd php70w-xsl php70w-json php70w-intl php70w-pear php70w-devel php70w-common php70w-mbstring php70w-tidy php70w-zip php70w-soap curl

After the installation is complete, we need to edit the ‘php.ini’ configuration file and edit the php-fpm pool configuration ‘www.conf’.

Edit the ‘php.ini’ configuration file using the vim editor.

vim /etc/php.ini

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

cgi.fix_pathinfo=0

Save and exit.

Next, edit the pool configuration file ‘www.conf’.

vim /etc/php-fpm.d/www.conf

Change the default user for running the PHP-FPM service to ‘nginx’ user and group.

user = nginx
group = nginx

On the ‘listen’ line, change the value to the sock file as below. We will be running PHP-fpm under the sock file.

listen = /var/run/php-fpm/php-fpm.sock

Now for the socket permission and owner configuration. Uncomment these lines and change the value as below.

listen.owner = nginx
listen.group = nginx
listen.mode = 0660

Finally, uncomment the PHP-FPM environment.

env[HOSTNAME] = $HOSTNAME
env[PATH] = /usr/local/bin:/usr/bin:/bin
env[TMP] = /tmp
env[TMPDIR] = /tmp
env[TEMP] = /tmp

Save and exit.

If the configuration is complete, start PHP-FPM service and enable it to launch everytime at boot time.

systemctl start php-fpm
systemctl enable php-fpm

Now check it using the netstat command.

netstat -pl | grep php

And make sure you get the PHP-FPM sock file.

PHP and PHP-FPM 7.0 with all extensions needed for the ‘BookStack’ platform has been installed on the CentOS 7 system.

Step 4 – Install and Configure MySQL/MariaDB

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

Run yum command below to install MariaDB database.

yum install -y mariadb mariadb-server

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

systemctl start mariadb
systemctl enable mariadb

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

Run the command below 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 the others, just type ‘Y’ for yes and press 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 now has been set up.

Next, we need to create a new MySQL database for BookStack installation. We will create a new database named ‘bookstackdb’ with user ‘bookstak’ and password ‘[email protected]‘.

Login to the MySQL shell with the root user.

mysql -u root -p

Run all MySQL queries below on the shell.

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 CentOS 7 system, and the database for ‘BookStack’ installation has been created.

Step 5 – Install PHP Composer on CentOS 7

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 try the ‘composer’ command as shown below.

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

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

The PHP Composer is now installed on CentOS 7 system.

Step 6 – Install BookStack on CentOS 7

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

Before installing ‘BookStack’, install git on your system.

yum -y install git

Now create new ‘/var/www’ directory.

mkdir -p /var/www

Go to that 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 needed using 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 ownership permissions of the ‘BookStack’ directory to the ‘nginx’ user and group.

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

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

In the root application directory ‘/var/www/BookStack’, run the following commands.

php artisan key:generate
php artisan migrate

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

Wait until the table migration is successful.

The BookStack application has been installed, with the secret unique key application generated and the database scheme for BookStack 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.

Go to the ‘/etc/nginx’ directory and create new virtual host file ‘bookstack.conf’ under the ‘conf.d/’ directory using vim editor.

cd /etc/nginx
vim conf.d/bookstack.conf

Paste 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:/var/run/php-fpm/php-fpm.sock;
  }
  location ~* \.(?:jpg|jpeg|gif|bmp|ico|png|css|js|swf)$ {
    expires 30d;
    access_log off;
  }
}

Save and exit.

Now test nginx configuration and make sure there is no error, then restart the nginx service.

nginx -t
systemctl restart nginx

The Nginx virtual host for BookStack application has been created 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 below.

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

You should get the BookStack user Dashboard.

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

Now click ‘Users’ 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.

The BookStack installation with LEMP (Linux, Nginx, MariaDB, and PHP-FPM) stack on CentOS 7 has been completed successfully.

Reference