Self-Host BookStack on Linux

Mục Lục

BookStack is a self-hosted wiki platform for organizing HomeLab documentation. This article adapts the complete Linux installation flow from i12bretro, including Apache, MariaDB, PHP, Composer, the .env file, and the Apache site configuration. Example credentials from the source are replaced with placeholders; generate your own secrets during deployment.

Source reference: i12bretro – Install BookStack on Linux . The original video belongs to i12bretro on YouTube .

Requirements

A Linux host with sudo access.
A hostname or domain for BookStack.
MariaDB, Apache, and PHP compatible with the BookStack release being installed.
A separate database password and an app key generated by Artisan.

Install the base packages

Log into the Linux host.
Update the package list:

1
sudo apt update

Install available updates:

1
sudo apt upgrade -y

Install the required tools:

1
sudo apt install git openssl curl wget zip composer -y

Install Apache and MariaDB:

1
sudo apt install apache2 mariadb-server mariadb-client -y

Install PHP and the extensions commonly required by BookStack:

1
sudo apt install php libapache2-mod-php php-curl php-tokenizer php-ldap php-cli php-json php-gd php-mbstring php-mysql php-xml php-zip php-bcmath -y

Secure MariaDB

Start the MariaDB security wizard:

1
sudo mysql_secure_installation

Press Enter at the root login prompt if the installation does not yet have a root password.
Choose Y to set a root password and enter it twice. Never put the real password in this article, logs, or Git.
Choose Y to remove anonymous users.
Choose Y to disallow remote root login.
Choose Y to remove the test database.
Choose Y to reload privilege tables.
Log into MariaDB:

1
mysql -u root -p

Enter the root password created earlier.
Create a dedicated BookStack database and user. Replace [DB_PASSWORD] with a secret stored outside the repository:

1
2
3
4
CREATE DATABASE bookstack;
GRANT ALL ON bookstack.* TO 'bookstack_rw'@'localhost' IDENTIFIED BY '[DB_PASSWORD]';
FLUSH PRIVILEGES;
EXIT;

Exit the shell if necessary:

1
exit

Download BookStack and create the environment file

Clone the release branch into /var/www/bookstack:

1
sudo git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch /var/www/bookstack

Copy the sample environment file:

1
sudo cp /var/www/bookstack/.env.example /var/www/bookstack/.env

Open the configuration file:

1
sudo nano /var/www/bookstack/.env

Adjust the main variables below. Do not use sample passwords, mail hosts, or app keys:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
APP_ENV=production
APP_DEBUG=false
APP_KEY=
APP_URL=http://DNSorIP/bookstack
APP_TIMEZONE=Asia/Ho_Chi_Minh
APP_LOCALE=en

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=bookstack
DB_USERNAME=bookstack_rw
DB_PASSWORD=[DB_PASSWORD]

MAIL_DRIVER=smtp
MAIL_HOST=[SMTP_HOST]
MAIL_PORT=25
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_FROM_ADDR=bookstack@[YOUR_DOMAIN]
MAIL_FROM_NAME='BookStack'
MAIL_REPLYTO_ADDR=bookstack@[YOUR_DOMAIN]
MAIL_REPLYTO_NAME='BookStack'
MAIL_AUTO_EMBED_METHOD='attachment'

Set APP_URL to the real URL. Use https:// when the site is served through HTTPS.
Press Ctrl+O, Enter, then Ctrl+X to save and close nano.

Install dependencies and generate the app key

Set the BookStack directory owner:

1
sudo chown -R www-data:www-data /var/www/bookstack

Create the Composer working directory and assign its owner:

1
2
sudo mkdir /var/www/.composer
sudo chown -R www-data:www-data /var/www/.composer

Change into the BookStack directory:

1
cd /var/www/bookstack

Install production dependencies:

1
sudo -u www-data composer install --no-dev --no-plugins

Generate the app key with Artisan:

1
sudo php artisan key:generate --no-interaction --force

Run the database migration:

1
sudo php artisan migrate --no-interaction --force

Open the Apache site configuration:

1
sudo nano /etc/apache2/sites-available/bookstack.conf

Add the following configuration and adjust the path/domain if using a different deployment path:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
Alias /bookstack "/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

        RewriteCond %{HTTP:Authorization} .
        RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteCond %{REQUEST_URI} (.+)/$
        RewriteRule ^ %1 [L,R=301]

        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteRule ^ index.php [L]
    </IfModule>
</Directory>

Press Ctrl+O, Enter, then Ctrl+X to save the file.
Enable rewrite, enable the BookStack site, and restart Apache:

1
2
3
sudo a2enmod rewrite
sudo a2ensite bookstack
sudo systemctl restart apache2

Complete the Web Installer

Open http://DNSorIP/bookstack.
Use the default first-login information only when confirmed by the BookStack version documentation; immediately replace it with a unique account and password.
Open the user dropdown in the top-right corner and select My Account.
Update the username and email, then click Save.
Select Access & Security in the left navigation.
Enter and confirm a new password, then click Update.
Open the user dropdown and select Logout.
Log in again with the updated email and password.
Verify that BookStack can read the database, write uploads, and load the wiki pages.

Operations note: Enable HTTPS, back up both the database and /var/www/bookstack, protect .env, disallow remote MariaDB root login, and test compatibility before updating the release branch.

Source and video

Original tutorial: i12bretro 0919
Original video: Install BookStack on Linux
BookStack manual installation: bookstackapp.com/docs/admin/installation
Repository: BookStackApp/BookStack

AIoT.IO.VN