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

 1 +++
 2 title = "Updating BookStack"
 3 description = "How to update BookStack to the lastest version"
 4 date = "2017-01-01"
 5 type = "admin-doc"
 6 +++
 7
 8 BookStack is updated regularly and is still in beta although we do try to keep the platform and upgrade path as stable as possible. The latest release can be found on [GitHub here](https://github.com/BookStackApp/BookStack/releases) and detailed information on releases is posted on the [BookStack blog here](/tags/releases/).
 9
 10 **Before updating you should back up the database and any file uploads to prevent potential data loss**. <br>
 11 Backup and restore documentation can be found [here](/docs/admin/backup-restore).
 12
 13  Updating is currently done via Git version control. To update BookStack you can run the following command in the root directory of the application:
 14
 15 ```bash
 16 git pull origin release && composer install --no-dev && php artisan migrate
 17 ```
 18
 19 This command will update the repository that was created in the installation, install the PHP dependencies using `composer` then run then update the database with any required changes.
 20
 21 In addition, Clearing the cache is also recommended:
 22
 23 ```bash
 24 php artisan cache:clear
 25 php artisan view:clear
 26 ```
 27
 28 Check the below list for the version you are updating to for any additional instructions.
 29
 30 ---
 31
 32 ## Version Specific Instructions
 33
 34 The below lists things you may need to be aware of when upgrading to a newer version of BookStack.
 35
 36 #### Updating to v0.30.5 or higher
 37
 38 **Security** - v0.30.5 fixes an potential vulnerability where a user with edit permissions could perform server-side requests using the export system. Additionally it was found that, if using standard email/password authentication, the system host URL could be manipulated on the forgot password form which could allow for email phishing attempts. Ensure you have set the `APP_URL` option in your `.env` file to help prevent this. Please see the [blog release page for more details](/blog/beta-release-v0-30-5/).
 39
 40 #### Updating to v0.30.4 or higher
 41
 42 **Security** - v0.30.4 fixes a couple of XSS vulnerabilities that could be exploited by untrusted users via page content and page link attachments. Please see the [blog release page for more details](/blog/beta-release-v0-30-4/).
 43
 44 #### Updating to v0.30 or higher
 45
 46 **Security** - Possible Privilege Escalation. During the v0.30 release cycle
 47 it was advised that current privilege escalation situations are not made clear when applying role permissions.
 48 Any user with a "Manage app settings", "Manage users" or "Manage roles & role permissions" system permission
 49 assigned to one of their roles could technically alter their own permissions to gain wider access.
 50 A clear advisory of these cases has been added in the UI in v0.30
 51 but admins are advised to review which users have these permissions with the above in mind.
 52
 53
 54 **LDAP & SAML Group Matching** - During the v0.30 release cycle it was found that
 55 BookStack roles would be matched to LDAP/SAML groups based upon the role display name, which is expected,
 56 but only those roles with a matching "name" value would be considered. This "name" field was redundant,
 57 and has now been removed, but it would store a cleaned version the first-set name of the role.
 58 All roles will now be considered before being matched on name which may mean that roles which did not sync before,
 59 that would have been expected to based on their name, may now start to sync.
 60
 61
 62 #### Updating to v0.29.3 or higher
 63
 64 **Security** - v0.29.3 fixes an issue where the names of restricted/private books could seen by those without permission, if added to a shelf. This issue was introduced in BookStack v0.28.0.
 65
 66 #### Updating to v0.29.2 or higher
 67
 68 **Security** - v0.29.2 fixes a XSS security vulnerability in the comment system, that was introduced in BookStack v0.18. Upon updating the command `php artisan bookstack:regenerate-comment-content` should be ran to regenerate comment content to ensure that it is safe.
 69
 70 #### Updating to v0.28 or higher
 71
 72 **Requirements Change** - Minimum PHP version has increased from 7.0.5 to 7.2.
 73
 74 If you installed BookStack on Ubuntu 16.04 using the install script, You should be able to upgrade your PHP version to 7.4 by running the following commands:
 75
 76 ```bash
 77 sudo add-apt-repository -y ppa:ondrej/php
 78 sudo apt update
 79 sudo apt install -y php7.4 php7.4-fpm php7.4-curl php7.4-mbstring php7.4-ldap php7.4-tidy php7.4-xml php7.4-zip php7.4-gd php7.4-mysql
 80 sudo sed -i.bak 's/php7\.0-fpm/php7.4-fpm/' /etc/nginx/sites-available/bookstack
 81 sudo systemctl restart nginx.service
 82 ```
 83
 84 #### Updating to v0.26 or higher
 85
 86 **Internet Explorer Support** - IE11 Support has now been dropped. We *may* support any critical issues for view-only scenarios otherwise please use a modern browser.
 87
 88 **Translations** - Since many interfaces and lines of text have been updated, It may take a little while for some translations to catch-up. Expect to see more English text than usual if you're using a non-English language option.
 89
 90 **Images** - Due to changes how images are handled, as detailed below, some types of images may become inaccessible. Old logo images will be deleted when changed. Unused Book/Shelf cover images & User profile images will be become inaccessible after the update so you may want to delete them before upgrade.
 91
 92 **Security** - On previous versions of BookStack it was possible for users to insert JavaScript via the Markdown editor using `on*` html attributes. These will now be removed on page render unless you have set `ALLOW_CONTENT_SCRIPTS=true`. If untrusted users has access to your BookStack you may want to scan for `<<space_char>>on` in the HTML column of the pages table to identify any malicious intent.
 93
 94 #### Updating to v0.25.3 or higher
 95
 96 **Security** - On previous versions of BookStack it was possible to upload PHP files via the image upload endpoints. If you have a BookStack instance where untrusted users could upload image files, and you were using the default file storage option, It would have been possible for the user to access anything that the PHP process could. This would likely include, at minimum, any credentials stored in the `.env` file.
 97
 98 #### Updating to v0.25.2 or higher
 99
 100 **Configuration Change** - The .env option `REDIS_CLUSTER` has now been removed. If more than one redis server is provided they will automatically be clustered by BookStack.
 101
 102 #### Updating to v0.25 or higher
 103
 104 **Security** - During the release cycle for Version v0.25 it was found that page content includes could leak their content as preview text to users that don’t have permission to view the included content. It’s recommended to re-save any pages that included other page content that’s restricted to ensure included text is not shown in page preview text.
 105
 106 **Requirements Change** - Minimum required version of PHP has changed from 7.0.0 to 7.0.5.
 107
 108 **Configuration Change** - The .env option `GRAVATAR_URL=false` has been replaced by `AVATAR_URL=false`.
 109
 110
 111 #### Updating to v0.24 or higher
 112
 113 Version v0.24 changes the way the homepage option is stored. After updating, You may need to re-configure this setting.
 114
 115 If updating from a much older BookStack version (Pre v0.20) you may need to update the permission and search indexes. You can do this by running the following commands from your BookStack install folder:
 116
 117 ```bash
 118 php artisan bookstack:regenerate-search
 119 php artisan bookstack:regenerate-permissions
 120 ```
 121
 122 #### Updating to v0.19 or higher
 123
 124 Version v0.19 needs the following requirement change:
 125
 126 * Minimum required version of PHP has changed from 5.6.4 to 7.0.0.
 127
 128 #### Updating to v0.18 or higher
 129
 130 Version v0.18 introduced a commenting system. After updating you should check the permissions for all roles if you'd like to enable comments for your users.
 131
 132 #### Updating to v0.13 or higher
 133
 134 The v0.13 release contained some new features and updates which change the requirements of BookStack.
 135
 136 * Minimum required version of PHP has changed from 5.5.9 to 5.6.4.
 137   Upgrade your PHP version if below 5.6.4.
 138 * PHP-Tidy extension is now required.
 139   - On Ubuntu 16.04 this can be installed via `sudo apt install php7.0-tidy`.
 140   - On Ubuntu 14.04 (Using the defauly PHP option) this can be installed via `sudo apt-get install php5-tidy`.
 141 * Page attachments will be stored in the `storage/uploads` folder (Unless you use Amazon S3). This folder will be created on update. Ensure your webserver has write permissions for this folder.