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-docs"
   6 +++
   7
   8 Below are some different methods of installing BookStack. If you cannot find a guide for your setup search the web for "Laravel install guides" relevant for your system as the process is mostly the same.
   9
  10 * [Manual](#manual)
  11 * [Docker](#docker)
  12 * [Ubuntu 16.04 Script](#ubuntu-1604)
  13 * [Community Guides](#community)
  14
  15 ## Manual Installation <a name="manual"></a>
  16
  17 #### Requirements
  18
  19 BookStack has similar requirements to Laravel:
  20
  21 * PHP >= 5.6.4, Will need to be usable from the command line.
  22 * PHP Extensions: `OpenSSL`, `PDO`, `MBstring`, `Tokenizer`, `GD`, `MySQLND`, `Tidy`
  23 * MySQL >= 5.6, Single DB *(All permissions advised since application manages schema)*
  24 * Git *(Not strictly required but helps manage updates)*
  25 * [Composer](https://getcomposer.org/)
  26
  27 #### Instructions
  28
  29 Ensure the above requirements are met before installing.
  30
  31 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/Laravel experience will currently benefit.
  32
  33 1. Clone the release branch of the BookStack GitHub repository into a folder.
  34
  35         ```bash
  36         git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch
  37         ```
  38
  39 2. `cd` into the application folder and run `composer install`.
  40 3. Copy the `.env.example` file to `.env` and fill with your own database and mail details.
  41 4. Ensure the `storage`, `bootstrap/cache` & `public/uploads` folders are writable by the web server.
  42 5. In the application root, Run `php artisan key:generate` to generate a unique application key.
  43 6. If not using Apache or if `.htaccess` files are disabled you will have to create some URL rewrite rules as shown below.
  44 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.
  45 8. Run `php artisan migrate` to update the database.
  46 9. Done! You can now login using the default admin details `[email protected]` with a password of `password`. It is recommended to change these details directly after first logging in.
  47
  48 #### URL Rewrite rules
  49
  50 **Apache**
  51 ```apache
  52 Options +FollowSymLinks
  53 RewriteEngine On
  54
  55 RewriteCond %{REQUEST_FILENAME} !-d
  56 RewriteCond %{REQUEST_FILENAME} !-f
  57 RewriteRule ^ index.php [L]
  58 ```
  59
  60 **Nginx**
  61 ```nginx
  62 location / {
  63     try_files $uri $uri/ /index.php?$query_string;
  64 }
  65 ```
  66
  67 ---
  68
  69 ## Docker Image <a name="docker"></a>
  70
  71 A community built docker image is available for those that prefer to use a containerised version of BookStack. This image runs on Apache and PHP7. A docker compose file is also available to bring up a whole BookStack environment which includes MySQL 5.7. Here are the links for the docker image:
  72
  73 * [GitHub repository including docker compose file](https://github.com/solidnerd/docker-bookstack)
  74 * [Docker Hub page](https://hub.docker.com/r/solidnerd/bookstack/)
  75
  76 ---
  77
  78 ## Ubuntu 16.04 Installation Script <a name="ubuntu-1604"></a>
  79
  80 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.
  81
  82 [Link to installation script](https://github.com/BookStackApp/devops/blob/master/scripts/installation-ubuntu-16.04.sh)
  83
  84 #### Running the Script
  85
  86 ```bash
  87 # Ensure you have read the above information about what this script does before executing these commands.
  88
  89 # Download the script
  90 wget https://raw.githubusercontent.com/BookStackApp/devops/master/scripts/installation-ubuntu-16.04.sh
  91
  92 # Make it executable
  93 chmod a+x installation-ubuntu-16.04.sh
  94
  95 # Run the script with admin permissions
  96 sudo ./installation-ubuntu-16.04.sh
  97 ```
  98
  99 ---
 100
 101 ## Community Guides <a name="community"></a>
 102
 103 This is a collection of guides created by awesome members of the BookStack community:
 104
 105 * [CentOS 7 Install by Deviant Engineer](https://deviantengineer.com/2017/02/bookstack-centos7/)