Admin Documentation

Installation

Below you can find details on how to install BookStack on your own hosting. There are a number of installation options available depending on your setup. The install process will require some knowledge of hosting a PHP web application & database.

Requirements

BookStack has the following requirements:

  • PHP >= 8.0.2
    • For installation and maintenance, you’ll need to be able to run php from the command line.
    • Required Extensions: OpenSSL, PDO, MBstring, iconv, Tokenizer, GD, MySQL, SimpleXML & DOM.
    • Optional Extensions: LDAP (If wanting to use LDAP Auth).
  • MySQL >= 5.7 or MariaDB >= 10.2
    • For the storage of BookStack content and data.
    • Single Database (All permissions advised since application manages schema)
  • Git Version Control
    • For application of updates when following our standard process.
  • Composer >= v2.0
    • For installation and management of our PHP dependencies.
  • A PHP Compatible Webserver
    • For usage with PHP and for serving static files.

Shared Hosting

BookStack does not currently support shared PHP hosting. There are too many differences between shared hosting providers and too many limitations to support the current install process although we would like to make this easier in the future. You can try searching for ‘Laravel Install Guides’ for your hosting provider as the process would be similar. Beware that modifying the application source files or applying large work-arounds could lead to security or stability issues.

Manual Installation

Ensure the above requirements are met before installing.

This project currently uses the release branch of the BookStack GitHub repository as a stable channel for providing updates. The installation is currently somewhat complicated and will be made simpler in future releases. Some PHP or Laravel experience will make this easier.

  1. Clone the release branch of the BookStack GitHub repository into a folder.
1

git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch
  1. cd into the application folder and run composer install --no-dev.
  2. Copy the .env.example file to .env and fill with your own database and mail details.
  3. Ensure the storage, bootstrap/cache & public/uploads folders are writable by the web server (More information here).
  4. In the application root, Run php artisan key:generate to generate a unique application key.
  5. If not using Apache or if .htaccess files are disabled you will have to create some URL rewrite rules as shown below.
  6. Set the web root on your server to point to the BookStack public folder. This is done with the root setting on Nginx or the DocumentRoot setting on Apache.
  7. Run php artisan migrate to update the database.
  8. Done! You can now login using the default admin details admin@admin.com with a password of password. You should change these details immediately after logging in for the first time.

Webserver Configuration

Docker Containers

Community docker setups are available for those that would prefer to use a containerised version of BookStack:

LinuxServer.io

solidnerd

Ubuntu 22.04 Installation Script

A script to install BookStack on a fresh instance of Ubuntu 22.04 is available. This script is ONLY FOR A FRESH OS, it will install Apache, MySQL 8.0 & PHP 8.1 and could OVERWRITE any existing web setup on the machine. It also does not set up mail settings or configure system security so you will have to do those separately. You can use the script as a reference if you’re installing on a non-fresh machine.

Running the Script

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Ensure you have read the above information about what this script does before executing these commands.

# Download the script
wget https://raw.githubusercontent.com/BookStackApp/devops/main/scripts/installation-ubuntu-22.04.sh

# Make it executable
chmod a+x installation-ubuntu-22.04.sh

# Run the script with admin permissions
sudo ./installation-ubuntu-22.04.sh

The script will output a log file for debugging within your current working directory when running the script. Permissions for the BookStack installation files & folders will be set based upon the user used to run the script.

Ubuntu 20.04 Installation Script

A script to install BookStack on a fresh instance of Ubuntu 20.04 is available. This script is ONLY FOR A FRESH OS, it will install Apache, MySQL 8.0 & PHP 8.2 and could OVERWRITE any existing web setup on the machine. It also does not set up mail settings or configure system security so you will have to do those separately. You can use the script as a reference if you’re installing on a non-fresh machine.

Running the Script

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Ensure you have read the above information about what this script does before executing these commands.

# Download the script
wget https://raw.githubusercontent.com/BookStackApp/devops/main/scripts/installation-ubuntu-20.04.sh

# Make it executable
chmod a+x installation-ubuntu-20.04.sh

# Run the script with admin permissions
sudo ./installation-ubuntu-20.04.sh

Ubuntu 18.04 Installation Script

A script to install BookStack on a fresh instance of Ubuntu 18.04 is available. This script is ONLY FOR A FRESH OS, it will install Apache, MySQL 5.7 & PHP 8.2 and could OVERWRITE any existing web setup on the machine. It also does not set up mail settings or configure system security so you will have to do those separately. You can use the script as a reference if you’re installing on a non-fresh machine.

Link to installation script

Running the Script

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Ensure you have read the above information about what this script does before executing these commands.

# Download the script
wget https://raw.githubusercontent.com/BookStackApp/devops/main/scripts/installation-ubuntu-18.04.sh

# Make it executable
chmod a+x installation-ubuntu-18.04.sh

# Run the script with admin permissions
sudo ./installation-ubuntu-18.04.sh

Community Guides

This is a collection of guides created by awesome members of the BookStack community:

In addition to written guides, there are a bunch community videos on YouTube in addition to the guides on the official BookStack YouTube channel or BookStack PeerTube channel.

Old Guides

The below are community guides that are no longer current, due to using old operating systems or installing out-of-date dependencies, but they are still listed here as a useful resource:

Other Hosting Options

Below are some alternative platforms and services that can be used to host BookStack.
Note: These are not tested, vetted nor supported by the official BookStack project in any manner.

  • Cloudron - A solution for running apps on your own server.
  • Uberspace - A European based hosting provider.
  • Home Assistant Community Add-on - For Home Assistant users.
  • Stellar Hosted - A European based managed hosting provider.
  • alwaysdata - A European based managed hosting provider.
  • PikaPods - Managed open source hosting, EU and US regions available.
  • YunoHost - A Debian-based distribution that automates personal web server installation.
  • Elestio - Managed hosting in common cloud services or on-premise.
  • Nexxwave - Managed application hosting in the EU.
  • Easypanel - A modern server control panel. You can use it to deploy BookStack on your own server.
  • K&T Host - US based managed BookStack hosting with a focus on high availability.

High Availability

Some enterprise environments may need to configure a “High Availability” setup of BookStack to include some operational redundancy. This type of setup is not needed for the vast majority of BookStack instances. For a “High Availability” BookStack setup you’ll likely need to consider the following:

  • High availability is not something we assure to support. There may be scenarios that will not allow availability.
    • For example: The BookStack upgrade process does not assure availability when ran.
  • Sessions and Cache use the local filesystem by default.
  • Uploaded files use the local filesystem by default.
  • The theme system and error log also use the local filesystem.
  • A simplistic health-check endpoint can be found at the /status URI.
    • This performs basic checks on subsystems.
    • This should return a HTTP error status code (>=400) on any failure otherwise a 200 status code.
Edit this Page