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/
5 Comments
Thanks it worked fine. just had to fix the path ErrorLog an CustomLog ( removed starting \ )
Thanks for the hint, I've fixed it in the documentation.
This was really helpful for me! Set it up in no time :-) I had to switch some commands due to Debian 11. Thanks for your work. Also Your blog is kinda a template for my homelab documentation. How did you manage to get the page navigation on the left side ? im looking for something like this... Thanks
RANDOMUSER and RANDOMPASSWORD are not really 'random' and quite easy to guess. Perhaps you should tell people to create a truly random user and password at this step. Otherwise depending on the server configuration it could be fairily easy to hack into the database (through phpmyadmin for example)
Commands ?