BookStack¶

License: MIT

This guide is tested with BookStack 26.03.4 on Uberspace v8.0.75. We can't guarantee it to work with newer versions.

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

BookStack 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:

Prerequisites¶

We're using PHP in the stable version 8.4:

[isabell@moondust ~]$ uberspace tool version set php 8.4
OK: Set version of php to 8.4

You'll need your MariaDB credentials:

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

Installation¶

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

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

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

[isabell@moondust ~]$ cd ~/www/bookstack
[isabell@moondust bookstack]$ 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
[…]

Configuration¶

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

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

Copy the sample configuration file .env.example.

[isabell@moondust ~]$ cd ~/www/bookstack
[isabell@moondust bookstack]$ cp .env.example .env

Use an editor of your choice to edit the .env file and change the values of:

DB_DATABASE
DB_USERNAME
DB_PASSWORD
APP_URL

Example configuration:

APP_URL=https://isabell.uber.space

DB_HOST=localhost
DB_DATABASE=isabell_bookstack
DB_USERNAME=isabell
DB_PASSWORD=MySuperSecretPassword

MAIL_DRIVER=sendmail
MAIL_FROM_NAME="BookStack"
MAIL_FROM=isabell@uber.space

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).

[isabell@moondust ~]$ cd ~/www/bookstack
[isabell@moondust bookstack]$ php artisan key:generate
**************************************
*     Application In Production!     *
**************************************

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

Application key set successfully.

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

[isabell@moondust ~]$ cd ~/www
[isabell@moondust www]$ rm -f html/nocontent.html; rmdir html
[isabell@moondust www]$ ln -s bookstack/public html

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

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

Then update the admin user with your own data:

[isabell@moondust ~]$ cd ~/www/bookstack
[isabell@moondust bookstack]$ php artisan bookstack:create-admin --name isabell --email isabell@uber.space --password MySuperSecretPassword --initial
Admin account with email "isabell@uber.space" successfully created!

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, run the following commands in the root directory of the application.

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

Next, start the actual migration.

[isabell@moondust ~]$ cd ~/www/bookstack
[isabell@moondust bookstack]$ php artisan migrate
[…]
[isabell@moondust bookstack]$

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

[isabell@moondust ~]$ cd ~/www/bookstack
[isabell@moondust bookstack]$ php artisan cache:clear
Cache cleared successfully.
[isabell@moondust bookstack]$ php artisan view:clear
Compiled views cleared!