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

   1 +++
   2 title = "Subdirectory Setup"
   3 description = "How to setup BookStack in a subdirectory"
   4 date = "2018-10-04"
   5 type = "admin-doc"
   6 +++
   7
   8 You may want to host BookStack on a "Subdirectory" of your website, For example `https://example.com/bookstack`. To achieve this you will need to make some alterations to your webserver config. The details for setting this up on Apache or Nginx can be found below. You'll need to follow the BookStack setup section after configuring any webserver.
   9
  10 If you are using Docker you will likely need to look into setting up reverse proxies instead of following the below.
  11
  12 - [BookStack Setup](#bookstack-setup)
  13 - [Apache Setup](#apache-setup)
  14 - [Nginx Setup](#nginx-setup)
  15
  16 ---
  17
  18 ### BookStack Setup
  19
  20 Within your `.env` file ensure you set the `APP_URL` parameter. This should be the base URL for your BookStack instance without a trailing slash. For example:
  21
  22 ```bash
  23 APP_URL=https://example.com/bookstack
  24 ```
  25
  26 ---
  27
  28 ### Apache Setup
  29
  30 Before following this, ensure you have apache installed along with PHP & ensure mod-php is enabled. This guide assumes a recent Ubuntu-like system is in use. To set-up the required rules, you will need to have mod-rewrite enabled:
  31
  32 ```bash
  33 sudo a2enmod rewrite
  34 ```
  35
  36 First, You will need to choose a folder to install BookStack into. This should be a separate directory from where your main website is being served from since you don't want to risk exposing any of the private BookStack files.
  37 By default Apache on Ubuntu serves from the `/var/www/html` directory. In this example, we'll use `/var/www/bookstack` to store our BookStack install. If you use a different path ensure you change that path in the below steps.
  38 Create this directory and follow the standard [BookStack install steps](/docs/admin/installation) to install BookStack into this folder. Once complete, following our example directory above, you should end up with a `.env` file in the `/var/www/bookstack` folder.
  39
  40 The next step is to alter your Apache configuration to serve any requests to your sub-path from our chosen folder. To do this you'll need to find and edit the Apache virtual-host config for your website. By default, this is often found at `/etc/apache2/sites-available/000-default.conf`. To edit this file you'll likely have to open it with admin permissions (using `sudo`).
  41
  42 Within the `<VirtualHost>` tags of this file you'll need to add the below additional configuration. Note, the `<VirtualHost>` tags should already exist and the `...` parts represent existing rules. You should only need to copy the middle section:
  43
  44 > [!TIP]
  45 > Make sure that DocumentRoot does not point to the path where you installed BookStack in.
  46 > This is the case, if you used the install script.
  47 > You may comment out DocumentRoot, create a new folder and define a path like /var/www/other-site
  48
  49 ```apache
  50 <VirtualHost *:80>
  51
  52     ...
  53
  54     # BookStack Configuration
  55     Alias "/bookstack" "/var/www/bookstack/public"
  56
  57     <Directory "/var/www/bookstack/public">
  58       Options FollowSymlinks
  59       AllowOverride None
  60       Require all granted
  61
  62       RewriteEngine On
  63       # Redirect Trailing Slashes If Not A Folder...
  64       RewriteCond %{REQUEST_FILENAME} !-d
  65       RewriteRule ^(.*)/$ /$1 [L,R=301]
  66
  67       # Handle Front Controller...
  68       RewriteCond %{REQUEST_FILENAME} !-d
  69       RewriteCond %{REQUEST_FILENAME} !-f
  70       RewriteRule ^ index.php [L]
  71     </Directory>
  72
  73
  74     <Directory "/var/www/bookstack">
  75       AllowOverride None
  76       Require all denied
  77     </Directory>
  78     # End BookStack Configuration
  79
  80     ...
  81
  82 </VirtualHost>
  83 ```
  84
  85 On line 6 in the above, beginning with `Alias`, You'll need to change `"/bookstack"` path to be the web 'subdirectory' you want to serve BookStack on. For example, If you wanted to serve BookStack on `https://example.com/docs` this would be `"/docs"`. Any instances of `/var/www/bookstack` in the above will need to be changed to the folder you installed BookStack in. The `/public` part of these paths should remain.
  86
  87 Once the configuration has been updated, you'll need to restart apache. On Ubuntu you can do this with the following command:
  88
  89 ```bash
  90 sudo systemctl restart apache2.service
  91 ```
  92
  93 Follow the above [BookStack Setup](#bookstack-setup) to add your new URL to your BookStack configuration. Once done you should be able to access your BookStack instance at your desired sub-path.
  94
  95 ---
  96
  97 ### Nginx Setup
  98
  99 Before following this, ensure you have Nginx installed along with php-fpm. This guide assumes a recent Ubuntu-like system is in use. You may need to alter steps to suit other operating systems.
 100 There are multiple ways to achieve this approach with Nginx. The below uses multiple Nginx server blocks and proxying to achieve sub-path serving which keeps the
 101 BookStack server configuration contained.
 102
 103 First, you will need to choose a folder to install BookStack into. This should be a separate directory from where your main website is being served from since you don't want to risk exposing any of the private BookStack files. Do not install BookStack to a child directory of any other website's web root.
 104
 105 By default Nginx on Ubuntu serves from the `/var/www/html` directory. In this example, we'll use `/var/www/bookstack` to store our BookStack install. If you use a different path ensure you change that path in the below steps.
 106 Create this directory and follow the standard [BookStack install steps](/docs/admin/installation) to install BookStack into this folder. Once complete, following our example directory above, you should end up with a `.env` file in the `/var/www/bookstack` folder.
 107
 108 The next step is to alter your Nginx configuration to serve any requests to your sub-path from our chosen folder. To do this you'll need to find and edit the Nginx config for your website. By default, this is often found at `/etc/nginx/sites-available/default`. To edit this file you'll likely have to open it with admin permissions (using `sudo`).
 109
 110 Within your existing config file, or within a new one, add a new server block as per the below:
 111
 112 ```nginx
 113 server {
 114   listen 8080;
 115   listen [::]:8080;
 116
 117   server_name localhost;
 118
 119   root /var/www/bookstack/public;
 120   index index.php index.html;
 121
 122   location / {
 123     try_files $uri $uri/ /index.php?$query_string;
 124   }
 125
 126   location ~ \.php$ {
 127     include snippets/fastcgi-php.conf;
 128     fastcgi_pass unix:/run/php/php7.4-fpm.sock;
 129   }
 130 }
 131 ```
 132
 133 This server block will host BookStack at `http://localhost:8080`. The port and server name used here are intentional since this is only intended to be directly used locally.
 134 Next, locate the `server {` block for your existing website. Within this block add the following location block:
 135
 136 ```nginx
 137 location /bookstack/ {
 138   proxy_pass http://localhost:8080/;
 139   proxy_redirect off;
 140 }
 141 ```
 142
 143 Tweak the `/bookstack/` part to match the path you want to serve BookStack on. The slashes used within both the `location` and `proxy_pass` lines are important to functionality.
 144 This block will tell Nginx to handle requests to `/bookstack/` by proxying them to our previously created BookStack `server {` block.
 145
 146 A full [example of this configuration can be seen here](https://github.com/BookStackApp/devops/blob/main/config/nginx/subpath-proxy-config).
 147
 148 Once done save your config files. You can often test your Nginx config is valid by running `sudo nginx -t`. If valid restart Nginx. On Ubuntu this can be done with the following command:
 149
 150 ```bash
 151 sudo systemctl restart nginx.service
 152 ```
 153
 154 Follow the above [BookStack Setup](#bookstack-setup) to add your new URL to your BookStack configuration. Once done you should be able to access your BookStack instance at your desired sub-path.