Self-Host BookStack on Linux

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

1. Log into the Linux host.
2. Update the package list:

sudo apt update

3. Install available updates:

sudo apt upgrade -y

4. Install the required tools:

sudo apt install git openssl curl wget zip composer -y

5. Install Apache and MariaDB:

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

6. Install PHP and the extensions commonly required by BookStack:

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

1. Start the MariaDB security wizard:

sudo mysql_secure_installation

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

mysql -u root -p

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

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

11. Exit the shell if necessary:

exit

Download BookStack and create the environment file

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

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

2. Copy the sample environment file:

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

3. Open the configuration file:

sudo nano /var/www/bookstack/.env

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

APP_ENV=productionAPP_DEBUG=falseAPP_KEY=APP_URL=http://DNSorIP/bookstackAPP_TIMEZONE=Asia/Ho_Chi_MinhAPP_LOCALE=enDB_CONNECTION=mysqlDB_HOST=127.0.0.1DB_DATABASE=bookstackDB_USERNAME=bookstack_rwDB_PASSWORD=[DB_PASSWORD]MAIL_DRIVER=smtpMAIL_HOST=[SMTP_HOST]MAIL_PORT=25MAIL_USERNAME=nullMAIL_PASSWORD=nullMAIL_ENCRYPTION=nullMAIL_FROM_ADDR=bookstack@[YOUR_DOMAIN]MAIL_FROM_NAME='BookStack'MAIL_REPLYTO_ADDR=bookstack@[YOUR_DOMAIN]MAIL_REPLYTO_NAME='BookStack'MAIL_AUTO_EMBED_METHOD='attachment'

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

Install dependencies and generate the app key

1. Set the BookStack directory owner:

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

2. Create the Composer working directory and assign its owner:

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

3. Change into the BookStack directory:

cd /var/www/bookstack

4. Install production dependencies:

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

5. Generate the app key with Artisan:

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

6. Run the database migration:

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

7. Open the Apache site configuration:

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

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

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>

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

sudo a2enmod rewritesudo a2ensite bookstacksudo systemctl restart apache2

Complete the Web Installer

1. Open http://DNSorIP/bookstack.
2. Use the default first-login information only when confirmed by the BookStack version documentation; immediately replace it with a unique account and password.
3. Open the user dropdown in the top-right corner and select My Account.
4. Update the username and email, then click Save.
5. Select Access & Security in the left navigation.
6. Enter and confirm a new password, then click Update.
7. Open the user dropdown and select Logout.
8. Log in again with the updated email and password.
9. 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