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/composer
QA: Running
composer about
should 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/" .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.
-
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('admin@admin.com', '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')"
@mariano-daniel How is Wiki.js going for you? Hopefully the deployment process was more straightforward than BookStack.
Apologies for the late reply, I had plans on deploying BookStack on a GCloud instance to verify the issues you are experiencing when I got more free time (which is right now) but it seems that Google Cloud Platform keeps rejecting my payment method.
In case you ever do come back to deploying BookStack, below are some things you can try to isolate whether the issue is from BookStack config itself or the GCloud config is to try the following:
curl -k localhost:80
).curl
, then via a remote machine on the internet (e.g. your PC).And lastly, thanks for sharing the buymeacoffee website! A very interesting website, wasn't aware of it. I appreciate the gesture and that is more than enough for me. 👍