Installation for Debian 10

This guide is based from BookStack's official documentation and has been tested this way with version 0.31.6. Unfortunately, the installation script for Ubuntu provided by BookStack does not work under Debian 10 due to dependencies, so the path described here goes through the script's steps manually in an adapted form.

Preparation

To set up BookStack on a freshly installed Debian 10, the required packages must first be installed. A web server (here: Apache2), a database server (here: MySQL) and PHP are needed:

apt update
apt install -y apache2 libapache2-mod-php7.3 php7.3 php7.3-fpm php7.3-curl php7.3-mbstring php7.3-ldap php7.3-tidy php7.3-xml php7.3-zip php7.3-gd php7.3-mysql mariadb-server mariadb-client git curl

Database Setup

Afterwards the security of the MySQL installation should be increased. Therefore, just follow the dialog of the script:

mysql_secure_installation

Next, we set up a database including a user for BookStack. The user is only needed to connect to the database, not to login to the web interface:

mysql -u root -p
CREATE DATABASE bookstack;
CREATE USER 'RANDOMUSER'@'localhost' IDENTIFIED BY 'RANDOMPASSWORD';
GRANT ALL ON bookstack.* TO 'RANDOMUSER'@'localhost';
FLUSH PRIVILEGES;
quit

Installation

Now we download BookStack from the official GitHub page:

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

Next, we download the composer and run the setup. You might want to delete the composer afterwards:

cd /var/www/bookstack
curl -s https://getcomposer.org/installer > composer-setup.php
php composer-setup.php --quiet
rm -f composer-setup.php
export COMPOSER_ALLOW_SUPERUSER=1
php composer.phar install --no-dev --no-plugins

BookStack Configuration

After installing successfully, we now connect BookStack to the database that has been set up. For this, we use the main configuration file, which we need to rename first:

cd /var/www/bookstack
mv .env.example .env

The following entries need to be adjusted:

  • APP_URL=http://HOSTNAME/
  • DB_HOST=localhost
  • DB_DATABASE=bookstack
  • DB_USERNAME=RANDOMUSER
  • DB_PASSWORD=RANDOMPASSWORD

Now we can generate the app key and populate the database:

php artisan key:generate --no-interaction --force
php artisan migrate --no-interaction --force

Finally, we adjust the permissions accordingly so that the web server has access to the required subfolders of BookStack:

chown www-data:www-data -R bootstrap/cache public/uploads storage
chmod -R 755 bootstrap/cache public/uploads storage

At this point the setup of BookStack is complete - what is still missing is the configuration of the web server.

Apache2 Configuration

IMPORTANT: The configuration shown here represents a basic configuration, which should not be accessible via the internet like this! More information you might want to look into: https://www.tecmint.com/apache-security-tips/

First of all the Apache2 module "mod_rewrite" must be activated:

a2enmod rewrite

Then create a virtual host file /etc/apache2/sites-available/bookstack.conf with the following content:

<VirtualHost *:80>
	ServerName FQDN
	ServerAdmin webmaster@localhost
	DocumentRoot /var/www/bookstack/public/

    <Directory /var/www/bookstack/public/>
        Options Indexes FollowSymLinks
        AllowOverride None
        Require all granted
        <IfModule mod_rewrite.c>
            <IfModule mod_negotiation.c>
                Options -MultiViews -Indexes
            </IfModule>

            RewriteEngine On

            # Handle Authorization Header
            RewriteCond %{HTTP:Authorization} .
            RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

            # Redirect Trailing Slashes If Not A Folder...
            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteCond %{REQUEST_URI} (.+)/$
            RewriteRule ^ %1 [L,R=301]

            # Handle Front Controller...
            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteCond %{REQUEST_FILENAME} !-f
            RewriteRule ^ index.php [L]
        </IfModule>
    </Directory>

	ErrorLog \${APACHE_LOG_DIR}/error.log
	CustomLog \${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

Once the file is created (don't forget to adjust the hostname in line 2), we can enable the configuration:

a2dissite 000-default.conf
a2ensite bookstack.conf
systemctl restart apache2

BookStack is now accessible by browser using the system's hostname/IP. The default login is:

admin@admin.com

password

In addition to securing Apache2, login via a public network should only be done via HTTPS (and certificate). Obviously, the default login should also be changed as soon as possible and the official documentation should be consulted: https://www.bookstackapp.com/docs/admin/security/