Installation: Installing BookStack (Debian 11)

The following guide assumes running the commands below as root for simplicity. Later in the guide directory permissions are restricted to follow the principle of least privilege.

1. Install dependencies.

   apt install -y git unzip apache2 php7.4 curl php7.4-fpm php7.4-curl php7.4-mbstring php7.4-ldap \
   php7.4-tidy php7.4-xml php7.4-zip php7.4-gd php7.4-mysql libapache2-mod-php7.4 \
   default-mysql-server
   

2. Setup database.

   # You can manually define the password below or autogenerate it.
   DB_PASS="$(head /dev/urandom | tr -dc A-Za-z0-9 | head -c 13)"
   
   # TODO: Consider moving away from 'mysql_native_password' to a more secure authentication mechanism.
   mysql -u root --execute="CREATE DATABASE bookstack;"
   mysql -u root --execute="CREATE USER 'bookstack'@'localhost' IDENTIFIED WITH mysql_native_password AS PASSWORD('$DB_PASS');"
   mysql -u root --execute="GRANT ALL ON bookstack.* TO 'bookstack'@'localhost';FLUSH PRIVILEGES;"
   

   QA: Running mysql -u root --execute="SELECT user FROM mysql.user" should show the created user 'bookstack'.

3. Install PHP package manager.

   # 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 --quiet
   rm composer-setup.php
   
   # Move composer to global installation
   mv composer.phar /usr/local/bin/composer
   

   QA: Running composer about should output some text.

4. Download BookStack PHP webapp files.

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

5. Define BookStack environment variables (Change BASE_URL value below!).

   # Change the BASE_URL value to either an IP or hostname. See the three examples below (delete all except one BASE_URL)
   BASE_URL=http://bookstack.mydomain.com
   BASE_URL=http://192.168.1.1:6875
   BASE_URL=http://localhost
   
   # Copy and update BookStack environment variables
   cp .env.example .env
   
   sed -i.bak "s@APP_URL=.*\$@APP_URL=$BASE_URL@" .env
   sed -i.bak 's/DB_DATABASE=.*$/DB_DATABASE=bookstack/' .env
   sed -i.bak 's/DB_USERNAME=.*$/DB_USERNAME=bookstack/' .env
   sed -i.bak "s/DB_PASSWORD=.*\$/DB_PASSWORD=$DB_PASS/" .env
   

   QA: Inspect the contents of the '.env' file and confirm that the four variables (APP_URL, DB_DATABASE, DB_USERNAME, DB_PASSWORD) have valid values.

6. Configure BookStack.

   # 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
   

7. Configure Apache to serve new BookStack app.

   # Set up apache
   a2enmod rewrite
   a2enmod php7.4
   
   # Create apache config file to serve webapp
   vim /etc/apache2/sites-available/bookstack.conf
       <VirtualHost *:80>
               # Set the 'ServerName' to a static IP address unless you have a DNS entry for the hostname already.
               ServerName 10.10.10.100
               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>
   

8. Verify config 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            # Disable default website
   systemctl restart apache2
   

9. Login into Bookstack: Browser > http://$BOOKSTACK_IP:80 > Login('admin@admin.com', 'password')

Common Issues

• Problem: I messed up during the mysql steps and lost the password! How can I reset the password for the 'bookstack' user?
• Solution: mysql -u root --execute="SET PASSWORD FOR 'bookstack'@'localhost' = PASSWORD('AWESOME_NEW_PASSWORD')"