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

   1 # Installation
   2
   3 * [Manual](#manual)
   4 * [Docker](#docker)
   5 * [Ubuntu 16.04 Script](#ubuntu-1604)
   6
   7 ## Manual Installation <a name="manual"></a>
   8
   9 #### Requirements
  10
  11 BookStack has similar requirements to Laravel:
  12
  13 * PHP >= 5.6.4, Will need to be usable from the command line.
  14 * PHP Extensions: `OpenSSL`, `PDO`, `MBstring`, `Tokenizer`, `GD`, `MySQLND`, `Tidy`
  15 * MySQL >= 5.6
  16 * Git (Not strictly required but helps manage updates)
  17 * [Composer](https://getcomposer.org/)
  18
  19 #### Instructions
  20
  21 Ensure the above requirements are met before installing.
  22
  23 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.
  24
  25 1. Clone the release branch of the BookStack GitHub repository into a folder.
  26
  27         ```
  28         git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch
  29         ```
  30
  31 2. `cd` into the application folder and run `composer install`.
  32 3. Copy the `.env.example` file to `.env` and fill with your own database and mail details.
  33 4. Ensure the `storage`, `bootstrap/cache` & `public/uploads` folders are writable by the web server.
  34 5. In the application root, Run `php artisan key:generate` to generate a unique application key.
  35 6. If not using Apache or if `.htaccess` files are disabled you will have to create some URL rewrite rules as shown below.
  36 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.
  37 8. Run `php artisan migrate` to update the database.
  38 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.
  39
  40 #### URL Rewrite rules
  41
  42 **Apache**
  43 ```
  44 Options +FollowSymLinks
  45 RewriteEngine On
  46
  47 RewriteCond %{REQUEST_FILENAME} !-d
  48 RewriteCond %{REQUEST_FILENAME} !-f
  49 RewriteRule ^ index.php [L]
  50 ```
  51
  52 **Nginx**
  53 ```
  54 location / {
  55     try_files $uri $uri/ /index.php?$query_string;
  56 }
  57 ```
  58
  59 ---
  60
  61 ## Docker Image <a name="docker"></a>
  62
  63 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:
  64
  65 * [GitHub repository including docker compose file](https://github.com/solidnerd/docker-bookstack)
  66 * [Docker Hub page](https://hub.docker.com/r/solidnerd/bookstack/)
  67
  68 ---
  69
  70 ## Ubuntu 16.04 Installation Script <a name="ubuntu-1604"></a>
  71
  72 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.
  73
  74 [Link to installation script](https://github.com/BookStackApp/devops/blob/master/scripts/installation-ubuntu-16.04.sh)
  75
  76 #### Running the Script
  77
  78 ``` bash
  79 # Ensure you have read the above information about what this script does before executing these commands.
  80
  81 # Download the script
  82 wget https://raw.githubusercontent.com/BookStackApp/devops/master/scripts/installation-ubuntu-16.04.sh
  83
  84 # Make it executable
  85 chmod a+x installation-ubuntu-16.04.sh
  86
  87 # Run the script with admin permissions
  88 sudo ./installation-ubuntu-16.04.sh
  89 ```