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 20.04 Script](#ubuntu-2004)
 15 * [Ubuntu 18.04 Script](#ubuntu-1804)
 16 * [Community Guides](#community)
 17 * [Other Hosting Options](#other)
 18 * [High Availability](#ha)
 19
 20 ---
 21
 22 <a name="requirements"></a>
 23
 24 ## Requirements
 25
 26 BookStack has the following requirements:
 27
 28 * **PHP** >= 7.3
 29     * For installation and maintenance, you'll need to be able to run `php` from the command line.
 30     * Required Extensions: *OpenSSL, PDO, MBstring, Tokenizer, GD, MySQL, SimpleXML & DOM*
 31 * **MySQL** >= 5.6 or **MariaDB** >= 10.0
 32     *  Single Database *(All permissions advised since application manages schema)*
 33 * **Git Version Control**
 34     * (Not strictly required but helps manage updates)
 35 * **[Composer](https://getcomposer.org/)** >= v2.0
 36
 37 ---
 38
 39 <a name="shared"></a>
 40
 41 ## Shared Hosting
 42
 43 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.
 44
 45 ---
 46
 47 <a name="manual"></a>
 48
 49 ## Manual Installation
 50
 51 Ensure the above requirements are met before installing.
 52
 53 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.
 54
 55 1. Clone the release branch of the BookStack GitHub repository into a folder.
 56 ```bash
 57 git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch
 58 ```
 59 2. `cd` into the application folder and run `composer install --no-dev`.
 60 3. Copy the `.env.example` file to `.env` and fill with your own database and mail details.
 61 4. Ensure the `storage`, `bootstrap/cache` & `public/uploads` folders are writable by the web server.
 62 5. In the application root, Run `php artisan key:generate` to generate a unique application key.
 63 6. If not using Apache or if `.htaccess` files are disabled you will have to create some URL rewrite rules as shown below.
 64 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.
 65 8. Run `php artisan migrate` to update the database.
 66 9. 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.
 67
 68 #### Webserver Configuration
 69
 70 - [Example Apache VirtualHost configuration](https://github.com/BookStackApp/devops/blob/main/config/apache/bookstack.conf)
 71 - [Example Nginx Server block](https://github.com/BookStackApp/devops/blob/main/config/nginx)
 72
 73 ---
 74
 75 <a name="docker"></a>
 76
 77 ## Docker Containers
 78
 79 Community docker setups are available for those that would prefer to use a containerised version of BookStack:
 80
 81 #### LinuxServer.io
 82
 83 * [GitHub Repository](https://github.com/linuxserver/docker-bookstack)
 84 * [GitHub container package](https://github.com/linuxserver/docker-bookstack/pkgs/container/bookstack)
 85
 86 #### solidnerd
 87
 88 * [GitHub Repository](https://github.com/solidnerd/docker-bookstack)
 89 * [Docker Hub page](https://hub.docker.com/r/solidnerd/bookstack/)
 90
 91 ---
 92
 93 <a name="ubuntu-2004"></a>
 94
 95 ## Ubuntu 20.04 Installation Script
 96
 97 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-7.4 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.
 98
 99 [Link to installation script](https://github.com/BookStackApp/devops/blob/main/scripts/installation-ubuntu-20.04.sh)
 100
 101 #### Running the Script
 102
 103 ```bash
 104 # Ensure you have read the above information about what this script does before executing these commands.
 105
 106 # Download the script
 107 wget https://raw.githubusercontent.com/BookStackApp/devops/main/scripts/installation-ubuntu-20.04.sh
 108
 109 # Make it executable
 110 chmod a+x installation-ubuntu-20.04.sh
 111
 112 # Run the script with admin permissions
 113 sudo ./installation-ubuntu-20.04.sh
 114 ```
 115
 116
 117 ---
 118
 119 <a name="ubuntu-1804"></a>
 120
 121 ## Ubuntu 18.04 Installation Script
 122
 123 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-7.4 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.
 124
 125 [Link to installation script](https://github.com/BookStackApp/devops/blob/main/scripts/installation-ubuntu-18.04.sh)
 126
 127 #### Running the Script
 128
 129 ```bash
 130 # Ensure you have read the above information about what this script does before executing these commands.
 131
 132 # Download the script
 133 wget https://raw.githubusercontent.com/BookStackApp/devops/main/scripts/installation-ubuntu-18.04.sh
 134
 135 # Make it executable
 136 chmod a+x installation-ubuntu-18.04.sh
 137
 138 # Run the script with admin permissions
 139 sudo ./installation-ubuntu-18.04.sh
 140 ```
 141
 142 ---
 143
 144 <a name="community"></a>
 145
 146 ## Community Guides
 147
 148 This is a collection of guides created by awesome members of the BookStack community:
 149
 150 * [CentOS 8 Install by Xhark](https://github.com/blogmotion/bm-bookstack-install/blob/master/bookstack-install-centos8.sh) - [french guide](http://blogmotion.fr/internet/bookstack-script-installation-centos-8-18255)
 151 * [CentOS 7 Install by Deviant Engineer](https://deviant.engineer/2017/02/bookstack-centos7/)
 152 * [Fedora 27 Install by Jared Busch](https://mangolassi.it/topic/16471/install-bookstack-on-fedora-27/)
 153
 154
 155 ---
 156
 157 <a name="other"></a>
 158
 159 ## Other Hosting Options
 160
 161 Below are some alternative platforms and services that can be used to host BookStack. <br>
 162 _**Note: These are not tested, vetted nor supported by the official BookStack project in any manner**_.
 163
 164 - [Cloudron](https://www.cloudron.io/store/com.bookstackapp.cloudronapp.html) - A solution for running apps on your own server.
 165 - [Uberspace](https://lab.uberspace.de/guide_bookstack.html) - A European based hosting provider.
 166 - [Home Assistant Community Add-on](https://github.com/hassio-addons/addon-bookstack) - For [Home Assistant](https://www.home-assistant.io/) users.
 167 - [Stellar Hosted](https://www.stellarhosted.com/bookstack/) - A European based managed hosting provider.
 168 - [alwaysdata](https://www.alwaysdata.com/en/marketplace/bookstack/?tags=referrer:bookstack) - A European based managed hosting provider.
 169
 170 ---
 171
 172 <a name="ha"></a>
 173
 174 ## High Availability
 175
 176 Some enterprise environments may need to configure a "High Availability" setup of BookStack to include some operational redundancy.
 177 **This type of setup is not needed for the vast majority of BookStack instances.**
 178 For a "High Availability" BookStack setup you'll likely need to consider the following:
 179
 180 - High availability is not something we assure to support. There may be scenarios that will not allow availability.
 181   - For example: The BookStack upgrade process does not assure availability when ran.
 182 - Sessions and Cache use the local filesystem by default.
 183   - The database/memcached/redis options allow sharing across instances.
 184   - [Cache and session options are documented here](/docs/admin/cache-session-config/).
 185 - Uploaded files use the local filesystem by default.
 186   - You could instead use S3 or an S3 like storage system for these files.
 187   - Alternatively you could mount/link the used directories to shared locations.
 188   - [Directory locations and storage options are documented here](/docs/admin/upload-config/).
 189 - The [theme system](/docs/admin/hacking-bookstack/#theme-system) and [error log](/docs/admin/debugging/) also use the local filesystem.
 190 - A simplistic health-check endpoint can be found at the `/status` URI.
 191   - This performs basic checks on subsystems.
 192   - This should return a HTTP error status code (>=400) on any failure otherwise a 200 status code.