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
Install EPEL Repository
Install Nginx
Install and Configure PHP-FPM
Install and Configure MySQL/MariaDB
Install PHP Composer
Install BookStack
Configure Nginx Virtual Host BookStack
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 'bookstack@'.
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 bookstack@localhost identified by 'bookstack@';
grant all privileges on bookstackdb.* to bookstack@localhost identified by 'bookstack@';
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 DB_PASSWORD=bookstack@
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
https://www.bookstackapp.com/docs/