Installing BookStack Wiki on cPanel Shared Hosting

BookStack is a simple, free, open-source, Laravel-based, wiki software organized into a hierarchy of bookshelfs, books, chapters, and pages. Check out their website and demo to learn more. Though installation on shared hosting is not currently recommended by the developers, it is certainly possible and works well in my experience. With just a few extra steps you’ll be filling those BookStack shelves in no time.

For the most part we’ll be following the “Manual Installation” section of their documentation and making some adjustments along the way.

Let’s get started, shall we?

UPDATE (3/29/2024): This method still works, tested with BookStack v24.02.2, however make sure you are running PHP 8.0.2 or greater for both web and CLI.

Prerequisites

As of BookStack v0.27.5 (the version this tutorial is based on), we’ll need to meet the following requirements:

• cPanel Login & SSH Access
  • I’ll be using the PuTTY SSH client for this tutorial.
• PHP >= 7.0.5
  • For installation and maintenance, you’ll need to be able to run php from the command line.
  • Required Extensions: OpenSSL, PDO, MBstring, Tokenizer, GD, MySQL, Tidy, SimpleXML & DOM
• MySQL >= 5.6
• Git Version Control
  • For installation you’ll need to be able to run git from the command line.
• Composer
  • For installation you’ll need to be able to run composer from the command line.

Installation

1. Log in to your cPanel account.
2. Use the MySQL Database Wizard to create a database and database user with all privileges to the database you’ve created. Take note of the full database name and user credentials for a later step.
3. SSH into your cPanel server using your login credentials.
4. Make sure you are in your home directory by running cd ~
5. Clone the release branch of the BookStack GitHub repository by running
   git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch. It will create a BookStack directory for you automatically.
6. Run cd BookStack to get into the application folder and then run composer install. It will take a few minutes to download all of the required packages.
7. Run cp .env.example .env to start your environment configuration file.
8. Run php artisan key:generate and confirm with a “yes” to generate a unique application key. This automatically updates the APP_KEY constant in your .env file.
9. Run nano .env and fill it with your database details from step 2; set the APP_URL to the expected full public-facing URL of your BookStack site; set your mail details; save and exit the editor.
   • Example .env file:

     APP_KEY=base64:ip93b4kVjnVZdDYPdW+leQQHHHPFM2yrqMZGhhn8hfc=
     APP_URL=https://www.howto.casa/bookstack
     DB_HOST=localhost
     DB_DATABASE=howto_bkstack
     DB_USERNAME=howto_bkstack
     DB_PASSWORD=ka$js08h3*2x
     MAIL_DRIVER=mail

10. Run php artisan migrate and confirm with a “yes” to prepare the database.
11. Run chmod u+w ~/BookStack/storage ~/BookStack/bootstrap/cache to ensure these folders are writable by the web server.
12. Ensure you are still in the ~/BookStack directory, then move the contents of the public folder into your ~/public_html directory or a sub-directory underneath if you are adding BookStack to an existing website. In our case we will run mkdir ~/public_html/bookstack and mv public/* public/.htaccess ~/public_html/bookstack to move them to ~/public_html/bookstack for a sub-directory installation.
13. Run chmod u+w ~/public_html/bookstack/uploads to ensure the folder is writable by the web server.
14. Change to your public installation directory, in our case we’ll run cd ~/public_html/bookstack.
15. Run nano .htaccess and add RewriteBase /bookstack/ on a line immediately below RewriteEngine On.
    • Note: If you are not installing into a sub-directory use RewriteBase /.
16. Run nano index.php and make the following changes:
    • On or around line 22 replace require __DIR__.'/../bootstrap/init.php';
      with require realpath($_SERVER['DOCUMENT_ROOT'].'/..').'/BookStack/bootstrap/init.php';.
    • On or around line 36 replace $app = require_once __DIR__.'/../bootstrap/app.php';
      with $app = require_once realpath($_SERVER['DOCUMENT_ROOT'].'/..').'/BookStack/bootstrap/app.php'; and immediately afterwards add the following line:
      $app->bind('path.public', function() { return __DIR__; });
17. Done! You can now navigate to your public-facing BookStack URL and login using the default admin details, admin@admin.com with a password of password. For security reasons, change these details immediately after logging in for the first time.