BookStack¶

BookStack is a simple, self-hosted, easy-to-use platform for organising and storing information (wiki).

It is specially designed to allow new users with basic word-processing skills to get involved in creating content. However, it offers advanced power features for users who need them.

Note

For this guide you should be familiar with the basic concepts of

License¶

BookStack is released under the MIT License. All relevant information can be found in the LICENSE file in the repository of the project.

Prerequisites¶

We’re using PHP in the stable version 8.1:

[isabell@stardust ~]$ uberspace tools version show php
Using 'PHP' version: '8.1'
[isabell@stardust ~]$

You’ll need your MySQL credentials. Get them with my_print_defaults:

[isabell@stardust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword
[isabell@stardust ~]$

Your domain needs to be set up:

[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$

Installation¶

To install BookStack clone the release branch of the official repository one level above your DocumentRoot using Git.

[isabell@stardust ~]$ cd /var/www/virtual/$USER/
[isabell@stardust isabell]$ git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch
Cloning into 'BookStack'...
remote: Enumerating objects: 53, done.
[…]
[isabell@stardust ~]$

cd into your BookStack directory and install the necessary dependencies using Composer.

[isabell@stardust isabell]$ cd BookStack
[isabell@stardust isabell]$ composer install --no-dev
Loading composer repositories with package information
Installing dependencies (including require-dev) from lock file
Package operations: 103 installs, 0 updates, 0 removals
[…]
[isabell@stardust ~]$

Configuration¶

We suggest you use an additional database for BookStack to save your data. You have to create this database first.

[isabell@stardust ~]$ mysql -e "CREATE DATABASE ${USER}_bookstack"
[isabell@stardust ~]$

Copy the sample configuration file .env.example. Then edit the .env file and change the values of DB_DATABASE, DB_USERNAME, DB_PASSWORD to reflect your MySQL credentials and APP_URL to reflect your domain, then save the file.

[isabell@stardust BookStack]$ cp .env.example .env
[isabell@stardust ~]$

Note

You can optionally configure BookStack to send emails in the same place.

To make your BookStack installation safe you need to create a unique application key (a random, 32-character string used e.g. to encrypt cookies). Make sure to confirm the command with yes.

[isabell@stardust BookStack]$ php artisan key:generate
**************************************
*     Application In Production!     *
**************************************

 Do you really wish to run this command? (yes/no) [no]:
 > yes

Application key set successfully.
[isabell@stardust ~]$

Remove your unused DocumentRoot and create a new symbolic link to the BookStack/public directory.

[isabell@stardust ~]$ cd /var/www/virtual/$USER/
[isabell@stardust isabell]$ rm -f html/nocontent.html; rmdir html
[isabell@stardust isabell]$ ln -s /var/www/virtual/$USER/BookStack/public html
[isabell@stardust isabell]$

Now use the following command to create and populate the tables in your database. Confirm the command with yes.

[isabell@stardust ~]$ cd /var/www/virtual/$USER/BookStack
[isabell@stardust BookStack]$ php artisan migrate
**************************************
*     Application In Production!     *
**************************************
Do you really wish to run this command? (yes/no) [no]:
> yes
Migration table created successfully.
[...]
[isabell@stardust ~]$

Finishing installation¶

After the configuration you can now login by visiting your domain and using the default login admin@admin.com with the password password. Change this standard user directly after your first login.

Warning

Change the standard user directly after your first login and use a strong password to prevent others from hacking your instance.

Updates¶

Note

Check the update feed regularly to stay informed about the newest version. Detailed information on releases is posted on the BookStack blog.

To update BookStack you can run the following command in the root directory of the application. This will update your installation via Git, install new dependencies via Composer and migrate your database. It’s possible that you need to confirm the steps while updating.

[isabell@stardust ~]$ cd /var/www/virtual/$USER/BookStack
[isabell@stardust BookStack]$ git pull origin release
From https://github.com/BookStackApp/BookStack
* branch            release    -> FETCH_HEAD
[…]
[isabell@stardust BookStack]$ composer install --no-dev
[…]
[isabell@stardust BookStack]$

Next, start the actual migration. You will be asked to migrate files after installation in a production environment, default option is “no”. However, some updates need to migrate files (i.E. v22.10.2), so you have to answer with “yes” at the end.

[isabell@stardust BookStack]$ php artisan migrate
[…]
[isabell@stardust BookStack]$

After updating your installation you should clean the cache to prevent errors.

[isabell@stardust ~]$ cd /var/www/virtual/$USER/BookStack
[isabell@stardust BookStack]$ php artisan cache:clear
Cache cleared successfully.
[isabell@stardust BookStack]$ php artisan view:clear
Compiled views cleared!
[isabell@stardust ~]$

Tested with BookStack v22.11.1 , Uberspace 7.1.15

Written by: Daniel Kratz <https://danielkratz.com>