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.
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.3:
[isabell@stardust ~]$ uberspace tools version show php
Using 'PHP' version: '8.3'
[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.
[isabell@stardust BookStack]$ cp .env.example .env
[isabell@stardust ~]$
Use an editor of your choice to 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.
APP_URL=https://isabell.uber.space
DB_HOST=localhost
DB_DATABASE=isabell_bookstack
DB_USERNAME=isabell
DB_PASSWORD=MySuperSecretPassword
MAIL_DRIVER=smtp
MAIL_FROM_NAME="BookStack"
MAIL_FROM=isabell@uber.space
MAIL_HOST=stardust.uberspace.de
MAIL_PORT=587
MAIL_USERNAME=isabell
MAIL_PASSWORD=MySuperSecretPassword
MAIL_ENCRYPTION=tls
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 v24.05.2 , Uberspace 7.15.15
Written by: Daniel Kratz <https://danielkratz.com>