BookStack Code Mirror - website/blob - content/docs/admin/upload-config.md

 1 +++
 2 title = "Configuring File Uploads"
 3 description = "Configuration for files uploads such as images and attachments"
 4 date = "2018-01-12"
 5 type = "admin-doc"
 6 +++
 7
 8 BookStack allows users to upload both images for content and files as attachments.
 9
 10 * [Storage Options](#storage-options)
 11 * [Changing Upload Limits](#changing-upload-limits)
 12 * [File Upload Timeout](#file-upload-timeout)
 13 * [File Upload Limit](#file-upload-limit)
 14
 15 **For information relating to security for file uploads please refer to the [Security Page](/docs/admin/security).**
 16
 17 ---
 18
 19 ### Storage Options
 20
 21 Within BookStack there are a few different options for storing files:
 22
 23 * **local** (Default) - Files are stored on the server running BookStack. Images are publically accessible, served by your websever, but attachments are secured behind BookStack's authentication.
 24 * **local_secure** - Same as local option but images are served by BookStack, enabling authentication on image requests. Provides higher security but is more system resource intensive and could induce performance issues.
 25 * **s3** - Store files externally on Amazon S3. Images are made publically accessible on upload.
 26
 27 For all options you can use the 'Enable higher security image uploads' in-app admin setting which appends a random string to each uploaded image name to make URL's hard to guess.
 28
 29 #### Local
 30
 31 This is the default storage mechanism in BookStack. It can be forced by setting the following in your `.env` file:
 32
 33 ```bash
 34 STORAGE_TYPE=local
 35 ```
 36
 37 * Image uploads location: `<bookstack_install_dir>/public/uploads/images`.
 38 * Attachment uploads location: `<bookstack_install_dir>/storage/uploads/files`.
 39
 40 #### Local (Secure)
 41
 42 The local secure option can be enabled by setting the following in your `.env` file:
 43
 44 ```bash
 45 STORAGE_TYPE=local_secure
 46 ```
 47
 48 After setting this option ensure you test system performance creating a page with many images and reload on that page multiple times to ensure your server can keep with the
 49 multitude of image requests.
 50
 51 * Image uploads location: `<bookstack_install_dir>/storage/uploads/images`.
 52 * Attachment uploads location: `<bookstack_install_dir>/storage/uploads/files`.
 53
 54 If you'd like to switch to this option from the default `local` storage system you'll first need to migrate existing image uploads to the image folder listed above.
 55
 56 #### S3
 57
 58 The Amazon s3 option can be enabled by setting the following in your `.env` file:
 59
 60 ```bash
 61 STORAGE_TYPE=s3
 62 STORAGE_S3_KEY=your-s3-key
 63 STORAGE_S3_SECRET=your-s3-secret
 64 STORAGE_S3_BUCKET=s3-bucket-name
 65 STORAGE_S3_REGION=s3-bucket-region
 66 ```
 67
 68 For performance reasons uploaded images are made public upon upload to your s3 bucket and fetched directly by the end user when viewing an image on BookStack. Attachments are not made public and are instead fetched by BookStack upon request. Exact security will depend on the configuration and policies of your bucket.
 69
 70 * Image uploads location: `<your_bucket>/uploads/images`.
 71 * Attachment uploads location: `<your_bucket>/uploads/files`.
 72
 73 By default BookStack will generate a valid Amazon S3 URL for uploaded images. If you'd prefer to use a different URL, that you have pointed at your bucket, you can add the below option to your `.env` file which will be used as a base URL for all image uploads:
 74
 75 ```bash
 76 STORAGE_URL=https://images.example.com
 77 ```
 78
 79 #### Non-Amazon, S3 Compatible Services
 80
 81 Via the s3 connection BookStack does support s3-compatible services such as [Minio](https://www.minio.io/). Read the above S3 details to get an idea of general setup.
 82 For non-Amazon services the configuration, to be placed in the `.env` file, is a little different:
 83
 84 ```bash
 85 STORAGE_TYPE=s3
 86 STORAGE_S3_KEY=your-service-key
 87 STORAGE_S3_SECRET=your-service-secret-key
 88 STORAGE_S3_BUCKET=your-service-bucket-name
 89
 90 STORAGE_S3_ENDPOINT=https://your-service-base-endpoint.com:8080
 91 STORAGE_URL=https://your-service-base-endpoint.com:8080/your-service-bucket-name
 92 ```
 93
 94 Take note of how the first part of the `STORAGE_URL` path is the bucket name. This is important to ensure image URLs are set correctly.
 95
 96 BookStack's functionality to set image URL's as publicly accessible will likely not work for third-party services so you'll need to ensure files under the `<your_bucket>/uploads/images` path have policy or permissions to be publicly accessible. If using Minio you can add the following to the bucket policy:
 97
 98 ![Minio Bucket Policy](/images/2019/01/minio_s3_policy.png)
 99
 100 #### Separate Image and Attachment Storage
 101
 102 If you'd prefer to store images and attachments via different storage options, you can use the below `.env` options to do so:
 103
 104 ```bash
 105 # Image storage system to use
 106 # Defaults to the value of STORAGE_TYPE if unset.
 107 # Accepts the same values as STORAGE_TYPE.
 108 STORAGE_IMAGE_TYPE=local
 109
 110 # Attachment storage system to use
 111 # Defaults to the value of STORAGE_TYPE if unset.
 112 # Accepts the same values as STORAGE_TYPE although 'local' will be forced to 'local_secure'.
 113 STORAGE_ATTACHMENT_TYPE=local_secure
 114  ```
 115
 116 ---
 117
 118 ### Changing Upload Limits
 119
 120 By default, a lot of server software has strict limits on upload sizes which causes errors when users upload new content. This is not configured as part of BookStack but as part of PHP and your web sever software. If you run into problems with upload size limits follow the below details for PHP and whichever web server you use:
 121
 122 #### PHP
 123
 124 PHP has two main variables which effect upload limits. Find your `php.ini` file and look for the following variables:
 125
 126 * `post_max_size`
 127 * `upload_max_filesize`
 128
 129 If the values of these variables are low increase them to something sensible that's not too high to cause issues. Unless you need something higher 10MB is a sensible value to enter for these values:
 130
 131 ```ini
 132 post_max_size = 10M
 133 upload_max_filesize = 10M
 134 ```
 135
 136 If wanting to upload files over 128MB, you may also need to adjust your PHP memory limit like so:
 137
 138 ```ini
 139 memory_limit = 256M
 140 ```
 141
 142 After updating these values ensure you restart your webserver and also PHP if using PHP-FPM or something similar.
 143
 144 #### NGINX
 145
 146 By default NGINX has a limit of 1MB on file uploads. To change this you will need to set the `client_max_body_size` variable. You can do this either in the http block in your `nginx.conf` file or in the server block set up for BookStack. Here's an example of increasing the limit it 10MB in the http block:
 147
 148 ```nginx
 149 http {
 150         #...
 151         client_max_body_size 100m;
 152         client_body_timeout 120s; # Default is 60, May need to be increased for very large uploads
 153         #...
 154 }
 155 ```
 156
 157 As per the example above, If you are expecting upload very large files where upload times will exceed 60 seconds you will also need to add the `client_body_timeout` variable with a large value.
 158
 159 After updating you NGINX configuration don't forget to restart NGINX. You can test the configuration beforehand with `nginx -t`.
 160
 161 #### Apache
 162
 163 Apache does not have any built-in limits which you will need to change but something to note is that if you are using apache and mod_php with `.htaccess` files enabled you may be able to set the above PHP variables in your `.htaccess` file like so:
 164
 165 ```apache
 166 php_value upload_max_filesize 10M
 167 php_value post_max_size 10M
 168 ```
 169
 170 ---
 171
 172 ### File Upload Timeout
 173
 174 File uploads in BookStack use a JavaScript library which has a default upload timeout of 60 seconds. This means that if the file that you are uploading does not upload completely to the server within 60 seconds, the system will timeout.
 175
 176 To modify this timeout, in BookStack settings, Find the 'Custom HTML head content' setting and add the below code. Note that this does not change any server-side upload limits, Your websever may still impose an upload limit.
 177
 178 ```html
 179 <script>
 180     // Set the file upload timeout to 120 seconds.
 181     // You can change '120' to be the number of seconds you want the timeout to be.
 182     window.uploadTimeout = 120 * 1000;
 183 </script>
 184 ```
 185
 186 ---
 187
 188 ### File Upload Limit
 189
 190 File uploads in BookStack use a JavaScript library which has a default upload size limit of 256MB. To modify this timeout, in BookStack settings, Find the 'Custom HTML head content' setting and add the below code. Note that this does not change any server-side upload limits, Your websever may still impose an upload limit.
 191
 192 ```html
 193 <script>
 194     // Set the file upload limit to 1.5GB.
 195     // The value is defined in MB.
 196     window.uploadLimit = 1500;
 197 </script>
 198 ```