BookStack Code Mirror - website/blob - content/blog/2024/bookstack-release-v24-05.md

   1 +++
   2 categories = ["Releases"]
   3 tags = ["Releases"]
   4 title = "BookStack Release v24.05"
   5 date = 2024-05-10T13:36:00Z
   6 author = "Dan Brown"
   7 image = "/images/blog-cover-images/cc-by-sa-3/seven-sisters-cliffs-david-iliff.jpg"
   8 slug = "bookstack-release-v24-05"
   9 draft = false
  10 +++
  11
  12 For this month we have a new BookStack feature release! This is mainly focused on updating
  13 the core underlying framework and some accompanying code, but that work comes with a sprinkling
  14 of extra additions and tweaks too.
  15
  16 * [Update instructions](/docs/admin/updates)
  17 * [GitHub release page](https://github.com/BookStackApp/BookStack/releases/tag/v24.05)
  18
  19 **Upgrade Notices**
  20
  21 Todo - Copy to updates page
  22 Todo - PHP Update notes on updates page - See https://github.com/BookStackApp/BookStack/issues/4893
  23
  24 - **PHP Version Requirement Change** - The minimum supported PHP version has changed from PHP 8.0.2 to PHP 8.1 in this release. Please see the [v24.05 version-specific update instructions](/docs/admin/updates/#updating-to-v2405-or-higher) for guidance on updating PHP.
  25 - **Composer Version Requirement Change** - The minimum supported composer version has changed from v2.0 to v2.2 in this release. Please see the ["Updating Composer" section](/docs/admin/updates/#updating-composer) of our updates page for guidance on updating.
  26 - **LDAP** - The `LDAP_USER_FILTER` BookStack option now uses `{user}` as a placeholder instead of `${user}` by default. The older `${user}` placeholder format is still supported but you may want to use the new format instead. This should not cause ant issues on existing instances, unless `{user}` was used as a literal part of your user filter which would be very unlikely.
  27 - **PDF Exports** - The `WKHTMLTOPDF` option is now considered deprecated, with the alternative being the newly added `EXPORT_PDF_COMMAND` which is detailed in [our documentation here](https://www.bookstackapp.com/docs/admin/pdf-rendering/#pdf-export-command). The `WKHTMLTOPDF` option will though remain supported for a number of feature releases though to avoid unexpected breaking changes.
  28 - **OIDC** - The OIDC "userinfo" endpoint may now be called in very rare scenarios where not all expected claims were being properly provided in the user ID Token, which could alter the details used for new users on access, and the groups obtained for user group/role sync, but only in edge case scenarios where functionality was not matching configuration before the update.
  29 - **Page Content** - Text links in page content will now be underlined by default for accessibility. Refer to [the release blogpost](https://www.bookstackapp.com/blog/bookstack-release-v24-05/#change-to-default-link-styles) for an simple customization to override & revert this if desired.
  30
  31 TODO - Video
  32 <!-- {{<pt 8w3F4aWqH3MProMwyQBf2d>}} -->
  33
  34
  35 ### Framework & PHP Requirement Update
  36
  37 The core aim of this release was to update the core framework BookStack uses from
  38 [Laravel](https://laravel.com/) 9 to 10 to help us stay on modern and supported dependencies.
  39 This requires a bump to the minimum version of PHP we support, from 8.0 to 8.1.
  40 This is something we typically do on a yearly basis, and keeps somewhat inline with the official
  41 support lifetime of PHP versions, where PHP 8.0 stopped being officially supported late last year.
  42
  43 Apart from the PHP requirement change, this should not really have any affect to normal BookStack use
  44 but it ensures we're keeping things maintained and on a modern codebase.
  45
  46 ### Command-based PDF Export Option
  47
  48 By default in BookStack we use a PHP-based PDF renderer ([DomPDF](https://github.com/dompdf/dompdf))
  49 and have long provided a more accurate alternative via [wkhtmltopdf](https://www.bookstackapp.com/docs/admin/pdf-rendering/#using-wkhtmltopdf).
  50 Unfortunately, wkhtmltopdf has become somewhat deprecated and is therefore dropping out of system repositories.
  51 Additionally, there were security considerations when using wkhtmltopdf in BookStack.
  52
  53 As an alternative to we've now added a generic command-based option for BookStack.
  54 Since PDF rendering can be a complex element, with different solutions having different strengths and weaknesses,
  55 we didn't want to support a specific new PDF renderer, but instead provide an interface that could be
  56 used with many external options. This option allows you to define a command, which will take an input HTML
  57 file argument, and an output PDF file argument, which BookStack will then call during an export.
  58 Existing solutions can then be directly called via this, or wrapped to work with this command-based interface.
  59
  60 Right now we have a couple of examples in our documentation, but these are marked unsafe due to security concerns.
  61 In the future we'd like to expand upon, and potentially build/maintain, some safer alternative examples.
  62
  63 TODO - Link to docs page above
  64
  65 ### Change to Default Link Styles
  66
  67 Within page content links are now underlined by default.
  68
  69 TODO - Image of link
  70
  71 We generally try to avoid change that can affect core user content within BookStack, but this
  72 has been done to improve default accessibility by providing an additional indicator of a link upon
  73 just the color, which may not be easy to identify to all.
  74
  75 If you'd prefer your links to remain non-underlined you can easily override this change by adding the following
  76 to your "Custom HTML Head Content" customization setting:
  77
  78 TODO - Code here
  79
  80 ### OIDC Userinfo Endpoint Support
  81
  82 When OIDC authentication was in use, BookStack would previously only read claims direction from the supplied
  83 user ID token. While this worked fine in most cases, some auth platforms would only provide certain details
  84 via the userinfo endpoint. In this release we add wider support of the OIDC spec by making use of the userinfo
  85 endpoint where needed. If not all details are in the token, BookStack will call & use the userinfo endpoint data.
  86 This means existing OIDC use-cases should remain speedy and unaffected, with extra calls only being made during
  87 authentication when needed.
  88
  89 The userinfo endpoint will be fetched via autodiscovery if enabled, otherwise it can also be defined via env options
  90 using an `OIDC_USERINFO_ENDPOINT` option. Our [OIDC documentation](/docs/admin/oidc-auth/) has been updated to include this.
  91
  92 Thanks to [@LukeShu](https://github.com/BookStackApp/BookStack/pull/4726) for starting the implementation of this one.
  93
  94 ### Simple Registration Honeypot
  95
  96 For instances with open registration, spam can be a problem. While we don't want get deep into the ever moving scope
  97 of spam prevention, this release adds a simple honeypot field to the registration to hopefully help at least
  98 filter some of the simplest spam bots out.
  99
 100 Thanks to [@nesges](https://github.com/BookStackApp/BookStack/pull/4970) for contributing this addition.
 101
 102 ### Audit Log API Endpoint
 103
 104 We continue to expand the capabilities of the API in this release with the addition of a
 105 list API endpoint for the audit log. This endpoint provides much the same data you'd be able
 106 to access when visiting the in-app Audit Log as an administrator. The endpoint requires
 107 the API user to have both "Manage app settings" and "Manage users" role permission since
 108 audit log data may contain sensitive information, and is unfiltered by item-level permissions.
 109
 110 This addition should be helpful to those that need external insight into BookStack activities,
 111 and those that like to standardise & centralise such audit data.
 112
 113 ### LDAP Custom TLS CA Cert Option
 114
 115 When using LDAP along with TLS, to encrypt connections, it could be common that custom
 116 certificates are used by the authentication platform. Such custom certificates could then throw
 117 errors due to not being issues by a trusted/known authority. While custom certificates could technically be configured
 118 via openldap, the methods/steps needed for this are not clear nor obvious.
 119 In this release, we now support a `LDAP_TLS_CA_CERT` option that can be set so BookStack will use a
 120 certain CA certificate, or a directory of many CA certificates.
 121
 122 You can find further details of this option in our [updated LDAP documentation](https://www.bookstackapp.com/docs/admin/ldap-auth/).
 123
 124 ### Translations
 125
 126 A big thanks once again to all the wonderful word weavers below that have helped translate BookStack
 127 since that last feature release:
 128
 129 - Name - *LAng - x words*
 130
 131 *\* Word counts are those tracked by Crowdin, indicating original EN words translated.*
 132
 133 ### Next Steps
 134
 135 In BookStack the default WYSIWYG page editor (and recent description/comment editor) is powered by library
 136 called TinyMCE. They've recently [changed the project](https://github.com/tinymce/tinymce/discussions/9496)
 137 to a GPLv2+ license which is incompatible with our MIT license for the project as a working whole.
 138 This is quite a big deal for us since it's such a core part of the project.
 139 I've opened a BookStack [discussion for this here](https://github.com/BookStackApp/BookStack/issues/4908).
 140 Over the next release cycle I'll be diving into this further to get a better idea of what route we'll take.
 141
 142 Last month we had the release of Ubuntu 24.04, for which we quickly published a [new install script](/docs/admin/installation/#ubuntu-2404),
 143 but to accompany this I'd like to record a new video guide, perhaps going a little bit deeper this time into topics like updates
 144 and other general maintenance tasks.
 145
 146 ### Full List of Changes
 147
 148 **Released in v24.05**
 149
 150 * Updated app framework from Laravel 9 to 10. ([#4903](https://github.com/BookStackApp/BookStack/pull/4903))
 151 * Added new command-based PDF export option. ([#4969](https://github.com/BookStackApp/BookStack/pull/4969), [#4732](https://github.com/BookStackApp/BookStack/issues/4732))
 152 * Added Audit Log API list endpoint. ([#4987](https://github.com/BookStackApp/BookStack/pull/4987), [#4316](https://github.com/BookStackApp/BookStack/issues/4316))
 153 * Added LDAP option to provide a custom CA cert. Thanks to [@mmoore2012](https://github.com/BookStackApp/BookStack/pull/4913). ([#4985](https://github.com/BookStackApp/BookStack/pull/4985), [#4913](https://github.com/BookStackApp/BookStack/pull/4913))
 154 * Added OIDC userinfo endpoint support. Thanks to [@LukeShu](https://github.com/BookStackApp/BookStack/pull/4726). ([#4955](https://github.com/BookStackApp/BookStack/pull/4955), [#4726](https://github.com/BookStackApp/BookStack/pull/4726), [#3873](https://github.com/BookStackApp/BookStack/issues/3873))
 155 * Added simple registration form honeypot. Thanks to [@nesges](https://github.com/BookStackApp/BookStack/pull/4970). ([#4970](https://github.com/BookStackApp/BookStack/pull/4970))
 156 * Added Scala to list of supported languages in code blocks. ([#4953](https://github.com/BookStackApp/BookStack/issues/4953))
 157 * Updated content links to be underlined by default for accessibility. ([#4939](https://github.com/BookStackApp/BookStack/issues/4939))
 158 * Updated dev Dockerfile with improvements. Thanks to [@C0rn3j](https://github.com/BookStackApp/BookStack/pull/4895). ([#4895](https://github.com/BookStackApp/BookStack/pull/4895))
 159 * Updated included images with extra compression to save data. Thanks to [@C0rn3j](https://github.com/BookStackApp/BookStack/pull/4904). ([#4904](https://github.com/BookStackApp/BookStack/pull/4904))
 160 * Updated JS build system to split markdown-focused packages to own file. ([#4930](https://github.com/BookStackApp/BookStack/pull/4930), [#4858](https://github.com/BookStackApp/BookStack/issues/4858))
 161 * Updated LDAP user filter option to support new placeholder format. ([#4967](https://github.com/BookStackApp/BookStack/issues/4967))
 162 * Updated minimum required PHP version from 8.0 to 8.1. ([#4894](https://github.com/BookStackApp/BookStack/pull/4894), [#4893](https://github.com/BookStackApp/BookStack/issues/4893))
 163 * Updated translations with latest Crowdin changes. ([#4890](https://github.com/BookStackApp/BookStack/pull/4890))
 164 * Fixed code direction in WYSWIYG editor lacking direction support in code editor. ([#4943](https://github.com/BookStackApp/BookStack/issues/4943))
 165 * Fixed difference of line-heights for paragraphs in tables between editor and page view. ([#4960](https://github.com/BookStackApp/BookStack/issues/4960))
 166 * Fixed extra space at the beginning of a translation. Thanks to [@johnroyer](https://github.com/BookStackApp/BookStack/pull/4972). ([#4972](https://github.com/BookStackApp/BookStack/pull/4972))
 167 * Fixed failing drag and drop of attachments into editor on Chrome. ([#4975](https://github.com/BookStackApp/BookStack/issues/4975))
 168 * Fixed incorrect tag counts when tagged items are in the recycle bin. ([#4892](https://github.com/BookStackApp/BookStack/issues/4892))
 169 * Fixed WYSIWYG object embeds in the editor showing image toolbar button. ([#4974](https://github.com/BookStackApp/BookStack/issues/4974))
 170 * Fixed WYSIWYG table cell format handling which could clear styles unexpectedly. ([#4964](https://github.com/BookStackApp/BookStack/issues/4964))
 171
 172 **Released in v24.02.3**
 173
 174 * Fixed non-working "Open Link In..." option for description editors. ([#4925](https://github.com/BookStackApp/BookStack/issues/4925))
 175 * Fixed failed reference loading when references are from recycle bin items. ([#4918](https://github.com/BookStackApp/BookStack/issues/4918))
 176 * Fixed failed code block rendering when a code language was not set. ([#4917](https://github.com/BookStackApp/BookStack/issues/4917))
 177 * Updated page editor max content widths to align with page display.  ([#4916](https://github.com/BookStackApp/BookStack/issues/4916))
 178
 179 **Released in v24.02.2**
 180
 181 * New version to address missed version and asset changes in v24.02.1. ([#4889](https://github.com/BookStackApp/BookStack/issues/4889))
 182
 183 **Released in v24.02.1**
 184
 185 * Updated translations with latest Crowdin changes. ([#4877](https://github.com/BookStackApp/BookStack/pull/4877))
 186 * Updated breadcrumb book & shelf lists to be name-ordered. ([#4876](https://github.com/BookStackApp/BookStack/issues/4876))
 187 * Updated MFA inputs to avoid auto-complete. Thanks to [@ImMattic](https://github.com/BookStackApp/BookStack/pull/4849). ([#4849](https://github.com/BookStackApp/BookStack/pull/4849))
 188 * Fixed non-breaking spaces causing combined words in page navigation. ([#4836](https://github.com/BookStackApp/BookStack/issues/4836))
 189 * Fixed page navigation click not jumping to headers in nested collapsible blocks. ([#4878](https://github.com/BookStackApp/BookStack/issues/4878))
 190
 191 ----
 192
 193 <span style="font-size: 0.8em;opacity:0.9;">Header Image Credits: <span>Photo by <a href="https://commons.wikimedia.org/wiki/File:Seven_Sisters_Panorama,_East_Sussex,_England_-_May_2009.jpg">David Iliff (CC-BY-SA-3)</a> - Image Modified</span></span>