Installation
Dependencies
The first few packages installed are needed throughout the installation guide. Some of them may already be installed in you system, depending on the system installation you did.
sudo apt-get install curl unzip mariadb-server
For the installation in a Debian server, you need to update the PHP packages. This is because at the moment of writting, Debian GNU/LInux 11 (bullseye) only supports PHP 7.x which is deprecated. Hence you need to embarque in the installation of PHP 8.2.
If more information, you can read the text file https://packages.sury.org/php/README.txt.
For this, you need to add the sury repos to your server :
curl -sSL https://packages.sury.org/php/README.txt | sudo bash -x
sudo apt-get update
Now we can also add the other packages that are needed :
sudo apt-get install php8.2 php8.2-xml libapache2-mod-php8.2 php8.2-fpm php8.2-curl php8.2-mbstring php8.2-ldap php8.2-tidy php8.2-zip php8.2-gd php8.2-mysql git
A little bit of cleaning and restarting apache2 must be done and voilà !
sudo systemctl restart apache2
php -v
sudo apt-get autoremove --purge php7.4
sudo apt-get autoremove --purge php7.4-common
Then we need to create the database with the user. I'm not sure if it is always obligatory, but in my case I needed start MySQL as root. Once inside mysql, we run the following commands:
CREATE DATABASE bookstack;
CREATE USER 'bookstack'@'localhost' IDENTIFIED WITH mysql_native_password AS PASSWORD('Put_your_password_here');
GRANT ALL ON bookstack.* TO 'bookstack'@'localhost';FLUSH PRIVILEGES;
To verify that everything went well, write the following command mysql -u root --execute="SELECT user FROM mysql.user". The bookstack user should appear.
There is still the PHP package manager that must be installed. Use the code down here, for more information visit the documentation of the project.
# Install composer
EXPECTED_CHECKSUM="$(php -r 'copy("https://composer.github.io/installer.sig", "php://stdout");')"
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
ACTUAL_CHECKSUM="$(php -r "echo hash_file('sha384', 'composer-setup.php');")"
if [ "$EXPECTED_CHECKSUM" != "$ACTUAL_CHECKSUM" ]
then
>&2 echo 'ERROR: Invalid composer installer checksum'
rm composer-setup.php
exit 1
fi
php composer-setup.php
rm composer-setup.php
# Move composer to global installation.
mv composer.phar /usr/local/bin/composer
To verify that everything went well, write the following command composer about. You should have some info about composer.
Install BookStack
We now proceed to download the PHP files via git. Most certainly, this commands must be excecuted as a sudo-user.
cd /var/www
git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch bookstack
We enter bookstack folder and copy the environment file as follows :
cd bookstack
cp .env.example .env
The file .env is used to change core configurations of the BookStack application. In our case, we will do a minimal configuration. with your favorite text editor (Viva Vim!) enter into .env and modifiy the following variables:
# The application URL (as an example, in this instance it is : https://jardin.icamole.fr)
# Other examples : http://localhost
# http://192.168.1.1:6875
APP_URL=http://bookstack.mydomain.com
# Data base values also need to be modified
# if you follow previous command, you only need to add your DB_PASSWORD
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=Put_your_password_here
You can now proceed to install and configure the application
# Install BookStack composer dependencies
export COMPOSER_ALLOW_SUPERUSER=1
php /usr/local/bin/composer install --no-dev --no-plugins
# Generate the application key
php artisan key:generate --no-interaction --force
# Migrate the databases
php artisan migrate --no-interaction --force
# Set file and folder permissions
chown www-data:www-data -R bootstrap/cache public/uploads storage && chmod -R 755 bootstrap/cache public/uploads storage
Almost there ! You can now configure the apache server. First you set it up :
a2enmod rewrite
a2enmod php8.2
Then you can configure the configuration file (which needs to be created). Now, take again your favorite text editor into /etc/apache2/sites-available/bookstack.conf and add the following information Attention the variable ServerName must be modified into your URL of preference:
<VirtualHost *:80>
# Set the 'ServerName' to a static IP address unless you have a DNS entry for the hostname already.
ServerName bookstack.mydomain.com
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>
You can now veify the configuraton file and enable it :
/usr/sbin/a2ensite bookstack.conf # You need to enable it before using `apachectl configtest`
/usr/sbin/apachectl configtest # You might see a `AH00558` warning message. It is safe to ignore (related to DNS lookup).
# The main thing to see is a `Syntax OK` message.
#/usr/sbin/a2dissite 000-default.conf # Depending on your confguration you may wish to disable default website.
systemctl restart apache2
Login into Bookstack:
- Browser : http://bookstack.mydomain.com:80
- Login : 'admin@admin.com' , 'password'
File permission
This step is not stricktly neccesary, nevertheless it will be needed to update. I took the same approach as recommended in the BookStack documentation: Filesystem Permission. This configuration is enough for the permission and security section.
Be careful, some options must be written for your own case :
- Username that we run updates with, here called
barry. - BookStack install folder, usually
/var/www/bookstack. - Web-server/php username called
www-datain Debian (as well as Ubuntu).
# Set the bookstack folders and files to be owned by the user barry and have the group www-data
sudo chown -R barry:www-data /var/www/bookstack
# Set all bookstack files and folders to be readable, writeable & executable by the user (barry) and
# readable & executable by the group and everyone else
sudo chmod -R 755 /var/www/bookstack
# For the listed directories, grant the group (www-data) write-access
sudo chmod -R 775 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache /var/www/bookstack/public/uploads
# Limit the .env file to only be readable by the user and group, and only writable by the user.
sudo chmod -R 640 /var/www/bookstack/.env
Going further
In my particular case, I added a certificate to be able to access the site via https rather than http. In that case you need to modify in the .env file the APP_URL variable into https://bookstack.mydomain.com. Then you need to install certbot and the apache plugin as well. The following commands shall faire l'affaire (do not forget to change the words your_domain and www.your_domain into your domain !) :
sudo add-apt-repository ppa:certbot/certbot
sudo apt install python-certbot-apache
sudo certbot --apache -d your_domain -d www.your_domain
Apparently the package python-certbot-apache is now named python3-certbot-apache just in case :)
Contact in case of errors or problems :D
icamole[ arrobas] tuta.io