BookStack Code Mirror - website/blob - content/docs/admin/installation.md

   1 +++
   2 title = "Installation"
   3 description = "How to install BookStack"
   4 date = "2017-01-01"
   5 type = "admin-doc"
   6 +++
   7
   8 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.
   9
  10 * [Requirements](#requirements)
  11 * [Shared Hosting](#shared)
  12 * [Manual](#manual)
  13 * [Docker](#docker)
  14 * [Ubuntu 24.04 Script](#ubuntu-2404)
  15 * [Ubuntu 22.04 Script](#ubuntu-2204)
  16 * [Ubuntu 20.04 Script](#ubuntu-2004)
  17 * [Ubuntu 18.04 Script](#ubuntu-1804)
  18 * [Community Guides](#community)
  19 * [Other Hosting Options](#other)
  20 * [High Availability](#ha)
  21
  22 ---
  23
  24 <a name="requirements"></a>
  25
  26 ## Requirements
  27
  28 BookStack has the following requirements:
  29
  30 * **PHP** >= 8.1
  31     * For installation and maintenance, you'll need to be able to run `php` from the command line.
  32     * Required Extensions: OpenSSL, PDO (nd_pdo_mysql), MBstring, iconv, Tokenizer, GD, MySQL, SimpleXML & DOM.
  33     * Optional Extensions: LDAP *(If wanting to use LDAP Auth)*.
  34 * **MySQL** >= 5.7 or **MariaDB** >= 10.2
  35     * For the storage of BookStack content and data.
  36     * Single Database *(All permissions advised since application manages schema)*
  37 * **Git Version Control**
  38     * For application of updates when following our standard process.
  39 * **[Composer](https://getcomposer.org/)** >= v2.2.0
  40     * For installation and management of our PHP dependencies.
  41 * **A PHP Compatible Webserver**
  42     * For usage with PHP and for serving static files.
  43
  44 ---
  45
  46 <a name="shared"></a>
  47
  48 ## Shared Hosting
  49
  50 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.
  51
  52 ---
  53
  54 <a name="manual"></a>
  55
  56 ## Manual Installation
  57
  58 Ensure the above requirements are met before installing.
  59
  60 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.
  61
  62 1. Clone the release branch of the BookStack GitHub repository into a folder.
  63 ```bash
  64 git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch
  65 ```
  66 2. `cd` into the application folder and run `composer install --no-dev`.
  67 3. Copy the `.env.example` file to `.env` and fill with your own database and mail details.
  68 4. Ensure the `storage`, `bootstrap/cache` & `public/uploads` folders are writable by the web server ([More information here](/docs/admin/filesystem-permissions/)).
  69 5. In the application root, Run `php artisan key:generate` to generate a unique application key.
  70 6. If not using Apache or if `.htaccess` files are disabled you will have to create some URL rewrite rules as shown below.
  71 7. 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.
  72 8. Run `php artisan migrate` to update the database.
  73 9. Done! You can now login using the default admin details `[email protected]` with a password of `password`. You should change these details immediately after logging in for the first time.
  74
  75 #### Webserver Configuration
  76
  77 - [Example Apache VirtualHost configuration](https://github.com/BookStackApp/devops/blob/main/config/apache/bookstack.conf)
  78 - [Example Nginx Server block](https://github.com/BookStackApp/devops/blob/main/config/nginx)
  79
  80 ---
  81
  82 <a name="docker"></a>
  83
  84 ## Docker Containers
  85
  86 Community docker setups are available for those that would prefer to use a containerised version of BookStack:
  87
  88 #### LinuxServer.io
  89
  90 * [GitHub Repository](https://github.com/linuxserver/docker-bookstack)
  91 * [GitHub container package](https://github.com/linuxserver/docker-bookstack/pkgs/container/bookstack)
  92
  93 #### solidnerd
  94
  95 * [GitHub Repository](https://github.com/solidnerd/docker-bookstack)
  96 * [Docker Hub page](https://hub.docker.com/r/solidnerd/bookstack/)
  97
  98 ---
  99
 100 <a name="ubuntu-2404"></a>
 101
 102 ## Ubuntu 24.04 Installation Script
 103
 104 A script to install BookStack on a fresh instance of Ubuntu 24.04 is available. This script is ONLY FOR A FRESH OS, it will install Apache, MySQL 8.0 & PHP 8.3 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.
 105
 106 - [Link to installation script](https://github.com/BookStackApp/devops/blob/main/scripts/installation-ubuntu-24.04.sh)
 107
 108 #### Running the Script
 109
 110 ```bash
 111 # Ensure you have read the above information about what this script does before executing these commands.
 112
 113 # Download the script
 114 wget https://raw.githubusercontent.com/BookStackApp/devops/main/scripts/installation-ubuntu-24.04.sh
 115
 116 # Make it executable
 117 chmod a+x installation-ubuntu-24.04.sh
 118
 119 # Run the script with admin permissions
 120 sudo ./installation-ubuntu-24.04.sh
 121 ```
 122
 123 The script will output a log file for debugging within your current working directory when running the script.
 124 Permissions for the BookStack installation files & folders will be set based upon the user used to run the script.
 125
 126 ---
 127
 128 <a name="ubuntu-2204"></a>
 129
 130 ## Ubuntu 22.04 Installation Script
 131
 132 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.
 133
 134 - [Link to installation script](https://github.com/BookStackApp/devops/blob/main/scripts/installation-ubuntu-22.04.sh)
 135 - [Video guide](https://foss.video/w/emk5bMzhRdk4qzDoq3R6xe)
 136
 137 #### Running the Script
 138
 139 ```bash
 140 # Ensure you have read the above information about what this script does before executing these commands.
 141
 142 # Download the script
 143 wget https://raw.githubusercontent.com/BookStackApp/devops/main/scripts/installation-ubuntu-22.04.sh
 144
 145 # Make it executable
 146 chmod a+x installation-ubuntu-22.04.sh
 147
 148 # Run the script with admin permissions
 149 sudo ./installation-ubuntu-22.04.sh
 150 ```
 151
 152 The script will output a log file for debugging within your current working directory when running the script.
 153 Permissions for the BookStack installation files & folders will be set based upon the user used to run the script.
 154
 155 ---
 156
 157 <a name="ubuntu-2004"></a>
 158
 159 ## Ubuntu 20.04 Installation Script
 160
 161 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.
 162
 163 - [Link to installation script](https://github.com/BookStackApp/devops/blob/main/scripts/installation-ubuntu-20.04.sh)
 164 - [Video guide](https://foss.video/w/59udkzBf8ftVPWutkBcuyM)
 165
 166 #### Running the Script
 167
 168 ```bash
 169 # Ensure you have read the above information about what this script does before executing these commands.
 170
 171 # Download the script
 172 wget https://raw.githubusercontent.com/BookStackApp/devops/main/scripts/installation-ubuntu-20.04.sh
 173
 174 # Make it executable
 175 chmod a+x installation-ubuntu-20.04.sh
 176
 177 # Run the script with admin permissions
 178 sudo ./installation-ubuntu-20.04.sh
 179 ```
 180
 181
 182 ---
 183
 184 <a name="ubuntu-1804"></a>
 185
 186 ## Ubuntu 18.04 Installation Script
 187
 188 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.
 189
 190 [Link to installation script](https://github.com/BookStackApp/devops/blob/main/scripts/installation-ubuntu-18.04.sh)
 191
 192 #### Running the Script
 193
 194 ```bash
 195 # Ensure you have read the above information about what this script does before executing these commands.
 196
 197 # Download the script
 198 wget https://raw.githubusercontent.com/BookStackApp/devops/main/scripts/installation-ubuntu-18.04.sh
 199
 200 # Make it executable
 201 chmod a+x installation-ubuntu-18.04.sh
 202
 203 # Run the script with admin permissions
 204 sudo ./installation-ubuntu-18.04.sh
 205 ```
 206
 207 ---
 208
 209 <a name="community"></a>
 210
 211 ## Community Guides
 212
 213 This is a collection of guides created by awesome members of the BookStack community:
 214
 215 * [Debian 11 with PHP 8.2 by @armando-femat](https://jardin.icamole.site/books/bookstack/page/installation)
 216 * [RedHat 8.9 with PHP 8.1 (Rocky, Alma, Oracle, etc.) by @xhark](https://github.com/blogmotion/bm-bookstack-install/) - [french guide](https://blogmotion.fr/internet/bookstack-script-installation-centos-8-18255)
 217 * [Sample Docker Swarm Stack by @neuroforgede](https://github.com/neuroforgede/bookstack-docker-swarm)
 218
 219 In addition to written guides, there are a bunch [community videos on YouTube](https://www.youtube.com/playlist?list=PLLIji4SLo6EiAUI5X3amBSB99HpabUqsS)
 220 in addition to the guides on the official [BookStack YouTube channel](https://www.youtube.com/c/BookStackApp)
 221 or [BookStack PeerTube channel](https://foss.video/c/bookstack/).
 222
 223 #### Old Guides
 224
 225 The below are community guides that are no longer current, due to using old operating systems or installing out-of-date dependencies,
 226 but they are still listed here as a useful resource:
 227
 228 * [CentOS 7 Install by Deviant Engineer](https://deviant.engineer/2017/02/bookstack-centos7/)
 229 * [Debian 11 Install by Othman Alikhan](https://gist.github.com/OthmanAlikhan/322f83a77c15dfd1c91a2afe0b6a6fc2)
 230 * [Fedora 27 Install by Jared Busch](https://mangolassi.it/topic/16471/install-bookstack-on-fedora-27/)
 231
 232 ---
 233
 234 <a name="other"></a>
 235
 236 ## Other Hosting Options
 237
 238 Below are some alternative platforms and services that can be used to host BookStack. <br>
 239 _**Note: These are not tested, vetted nor supported by the official BookStack project in any manner**_.
 240
 241 - [Cloudron](https://www.cloudron.io/store/com.bookstackapp.cloudronapp.html) - A solution for running apps on your own server.
 242 - [Uberspace](https://lab.uberspace.de/guide_bookstack.html) - A European based hosting provider.
 243 - [Home Assistant Community Add-on](https://github.com/hassio-addons/addon-bookstack) - For [Home Assistant](https://www.home-assistant.io/) users.
 244 - [Stellar Hosted](https://www.stellarhosted.com/bookstack/) - A European based managed hosting provider.
 245 - [alwaysdata](https://www.alwaysdata.com/en/marketplace/bookstack/) - A European based managed hosting provider.
 246 - [PikaPods](https://www.pikapods.com/pods?run=bookstack) - Managed open source hosting, EU and US regions available.
 247 - [YunoHost](https://install-app.yunohost.org/?app=bookstack) - A Debian-based distribution that automates personal web server installation.
 248 - [Elestio](https://elest.io/open-source/bookstack) - Managed hosting in common cloud services or on-premise.
 249 - [Nexxwave](https://www.nexxwave.eu/app-hosting/bookstack) - Managed application hosting in the EU.
 250 - [Easypanel](https://easypanel.io/docs/templates/bookstack) - A modern server control panel. You can use it to deploy BookStack on your own server.
 251 - [K&T Host](https://www.knthost.com/bookstack) - US based managed BookStack hosting with a focus on high availability.
 252
 253 ---
 254
 255 <a name="ha"></a>
 256
 257 ## High Availability
 258
 259 Some enterprise environments may need to configure a "High Availability" setup of BookStack to include some operational redundancy.
 260 **This type of setup is not needed for the vast majority of BookStack instances.**
 261 For a "High Availability" BookStack setup you'll likely need to consider the following:
 262
 263 - High availability is not something we assure to support. There may be scenarios that will not allow availability.
 264   - For example: The BookStack upgrade process does not assure availability when ran.
 265 - Sessions and Cache use the local filesystem by default.
 266   - The database/memcached/redis options allow sharing across instances.
 267   - [Cache and session options are documented here](/docs/admin/cache-session-config/).
 268 - Uploaded files use the local filesystem by default.
 269   - You could instead use S3 or an S3 like storage system for these files.
 270   - Alternatively you could mount/link the used directories to shared locations.
 271   - [Directory locations and storage options are documented here](/docs/admin/upload-config/).
 272 - The [theme system](/docs/admin/hacking-bookstack/#theme-system) and [error log](/docs/admin/debugging/) also use the local filesystem.
 273 - A simplistic health-check endpoint can be found at the `/status` URI.
 274   - This performs basic checks on subsystems.
 275   - This should return a HTTP error status code (>=400) on any failure otherwise a 200 status code.