Skip to main content



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 For this, you need to add the sury repos to your server :

curl -sSL | 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 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("", "php://stdout");')"
php -r "copy('', 'composer-setup.php');"
ACTUAL_CHECKSUM="$(php -r "echo hash_file('sha384', 'composer-setup.php');")"

    >&2 echo 'ERROR: Invalid composer installer checksum'
    rm composer-setup.php
    exit 1

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 --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 :
# Other examples : http://localhost  

# Data base values also need to be modified
# if you follow previous command, you only need to add your DB_PASSWORD

You can now proceed to install and configure the application

# Install BookStack composer dependencies
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.
            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
                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]
            ErrorLog ${APACHE_LOG_DIR}/error.log
            CustomLog ${APACHE_LOG_DIR}/access.log combined

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 :
  • Login : '' , '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-data in 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 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]