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 * [Ubuntu 16.04 Script](#ubuntu-1604)
 17 * [Community Guides](#community)
 18
 19 ---
 20
 21 <a name="requirements"></a>
 22
 23 ## Requirements
 24
 25 BookStack has the following requirements:
 26
 27 * **PHP** >= 7.2
 28     * For installation and maintenence, you'll need to be able to run `php` from the command line.
 29     * Required Extensions: *OpenSSL, PDO, MBstring, Tokenizer, GD, MySQL, Tidy, SimpleXML & DOM*
 30 * **MySQL** >= 5.6
 31     *  Single Database *(All permissions advised since application manages schema)*
 32 * **Git Version Control**
 33     * (Not strictly required but helps manage updates)
 34 * **[Composer](https://getcomposer.org/)**
 35
 36 ---
 37
 38 <a name="shared"></a>
 39
 40 ## Shared Hosting
 41
 42 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.
 43
 44 ---
 45
 46 <a name="manual"></a>
 47
 48 ## Manual Installation
 49
 50 Ensure the above requirements are met before installing.
 51
 52 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.
 53
 54 1. Clone the release branch of the BookStack GitHub repository into a folder.
 55 ```bash
 56 git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch
 57 ```
 58 2. `cd` into the application folder and run `composer install --no-dev`.
 59 3. Copy the `.env.example` file to `.env` and fill with your own database and mail details.
 60 4. Ensure the `storage`, `bootstrap/cache` & `public/uploads` folders are writable by the web server.
 61 5. In the application root, Run `php artisan key:generate` to generate a unique application key.
 62 6. If not using Apache or if `.htaccess` files are disabled you will have to create some URL rewrite rules as shown below.
 63 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.
 64 8. Run `php artisan migrate` to update the database.
 65 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.
 66
 67 #### URL Rewrite rules
 68
 69 **Apache**
 70 ```apache
 71 Options +FollowSymLinks
 72 RewriteEngine On
 73
 74 RewriteCond %{REQUEST_FILENAME} !-d
 75 RewriteCond %{REQUEST_FILENAME} !-f
 76 RewriteRule ^ index.php [L]
 77 ```
 78
 79 **Nginx**
 80 ```nginx
 81 location / {
 82     try_files $uri $uri/ /index.php?$query_string;
 83 }
 84 ```
 85
 86 ---
 87
 88 <a name="docker"></a>
 89
 90 ## Docker Containers
 91
 92 Community docker setups are available for those that would prefer to use a containerised version of BookStack:
 93
 94 #### LinuxServer.io
 95
 96 * [GitHub Repository](https://github.com/linuxserver/docker-bookstack)
 97 * [Docker Hub page](https://hub.docker.com/r/linuxserver/bookstack)
 98
 99 #### solidnerd
 100
 101 * [GitHub Repository](https://github.com/solidnerd/docker-bookstack)
 102 * [Docker Hub page](https://hub.docker.com/r/solidnerd/bookstack/)
 103
 104 ---
 105
 106 <a name="ubuntu-2004"></a>
 107
 108 ## Ubuntu 20.04 Installation Script
 109
 110 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.
 111
 112 [Link to installation script](https://github.com/BookStackApp/devops/blob/master/scripts/installation-ubuntu-20.04.sh)
 113
 114 #### Running the Script
 115
 116 ```bash
 117 # Ensure you have read the above information about what this script does before executing these commands.
 118
 119 # Download the script
 120 wget https://raw.githubusercontent.com/BookStackApp/devops/master/scripts/installation-ubuntu-20.04.sh
 121
 122 # Make it executable
 123 chmod a+x installation-ubuntu-20.04.sh
 124
 125 # Run the script with admin permissions
 126 sudo ./installation-ubuntu-20.04.sh
 127 ```
 128
 129
 130 ---
 131
 132 <a name="ubuntu-1804"></a>
 133
 134 ## Ubuntu 18.04 Installation Script
 135
 136 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.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.
 137
 138 [Link to installation script](https://github.com/BookStackApp/devops/blob/master/scripts/installation-ubuntu-18.04.sh)
 139
 140 #### Running the Script
 141
 142 ```bash
 143 # Ensure you have read the above information about what this script does before executing these commands.
 144
 145 # Download the script
 146 wget https://raw.githubusercontent.com/BookStackApp/devops/master/scripts/installation-ubuntu-18.04.sh
 147
 148 # Make it executable
 149 chmod a+x installation-ubuntu-18.04.sh
 150
 151 # Run the script with admin permissions
 152 sudo ./installation-ubuntu-18.04.sh
 153 ```
 154
 155 ---
 156
 157 <a name="ubuntu-1604"></a>
 158
 159 ## Ubuntu 16.04 Installation Script
 160
 161 A script to install BookStack on a fresh instance of Ubuntu 16.04 is available. This script is ONLY FOR A FRESH OS, It will install Nginx, MySQL 5.7 & PHP7 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/master/scripts/installation-ubuntu-16.04.sh)
 164
 165 #### Running the Script
 166
 167 ```bash
 168 # Ensure you have read the above information about what this script does before executing these commands.
 169
 170 # Download the script
 171 wget https://raw.githubusercontent.com/BookStackApp/devops/master/scripts/installation-ubuntu-16.04.sh
 172
 173 # Make it executable
 174 chmod a+x installation-ubuntu-16.04.sh
 175
 176 # Run the script with admin permissions
 177 sudo ./installation-ubuntu-16.04.sh
 178 ```
 179
 180 ---
 181
 182 <a name="community"></a>
 183
 184 ## Community Guides
 185
 186 This is a collection of guides created by awesome members of the BookStack community:
 187
 188 * [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)
 189 * [CentOS 7 Install by Deviant Engineer](https://deviant.engineer/2017/02/bookstack-centos7/)
 190 * [Fedora 27 Install by Jared Busch](https://mangolassi.it/topic/16471/install-bookstack-on-fedora-27/)