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.
-
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 -
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'. -
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/composerQA: Running
composer aboutshould output some text. -
Download BookStack PHP webapp files.
cd /var/www git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch bookstack cd bookstack -
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/" .envQA: Inspect the contents of the '.env' file and confirm that the four variables (APP_URL, DB_DATABASE, DB_USERNAME, DB_PASSWORD) have valid values.
-
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 -
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> -
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 -
Login into Bookstack: Browser > http://$BOOKSTACK_IP:80 > Login('[email protected]', 'password')
- 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')"
Ye, that should have been done automatically in Step 5 with sed but I recall once or twice I had an issue with that. Perhaps when I get some time later I will update the guide to include common issues and solutions. Thanks for posting.
Edit 1: Improved the script for the .env section.