draft = false
+++
-Todo - Doc Updates
-
-Todo
+For this month we have a new BookStack feature release! This is mainly focused on updating
+the core underlying framework and some accompanying code, but that work comes with a sprinkling
+of extra additions and tweaks too.
* [Update instructions](/docs/admin/updates)
* [GitHub release page](https://github.com/BookStackApp/BookStack/releases/tag/v24.05)
**Upgrade Notices**
-Todo
Todo - Copy to updates page
-
-- **Item** - Note
+Todo - PHP Update notes on updates page - See https://github.com/BookStackApp/BookStack/issues/4893
+
+- **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.
+- **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.
+- **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.
+- **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.
+- **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.
+- **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.
TODO - Video
<!-- {{<pt 8w3F4aWqH3MProMwyQBf2d>}} -->
BookStack has the following requirements:
-* **PHP** >= 8.0.2
+* **PHP** >= 8.1
* For installation and maintenance, you'll need to be able to run `php` from the command line.
* Required Extensions: OpenSSL, PDO, MBstring, iconv, Tokenizer, GD, MySQL, SimpleXML & DOM.
* Optional Extensions: LDAP *(If wanting to use LDAP Auth)*.
* Single Database *(All permissions advised since application manages schema)*
* **Git Version Control**
* For application of updates when following our standard process.
-* **[Composer](https://getcomposer.org/)** >= v2.0
+* **[Composer](https://getcomposer.org/)** >= v2.2.0
* For installation and management of our PHP dependencies.
* **A PHP Compatible Webserver**
* For usage with PHP and for serving static files.
LDAP_PASS="my#super#secret#password543"
# A filter to use when searching for users
-# The user-provided user-name used to replace any occurrences of '${user}'
-# If you're setting this option via other means, such as within a docker-compose.yml,
-# you may need escape the $, often using $$ or \$ instead.
-# Note: This option cannot be used with the docker-compose.yml `env_file` option.
-LDAP_USER_FILTER=(&(uid=${user}))
+# The user-provided user-name used to replace any occurrences of '{user}'.
+# (Also supported via '${user}' for backwards compatibility.
+LDAP_USER_FILTER=(&(uid={user}))
# Set the LDAP version to use when connecting to the server
# Should be set to 3 in most cases.
# Defaults to 'false'.
LDAP_START_TLS=false
+# Certificate Authority Certificates to use for LDAP TLS connections.
+# Generally not needed if using a publicly trusted certificates.
+# Value should be a path to a specific CA certificate in pem format,
+# or a directory path where certificates are named via hashes, as
+# can be managed by a utility like "c_rehash".
+# Defaults to 'false'.
+#LDAP_TLS_CA_CERT=/etc/ldap/certs
+
# If you need to allow untrusted LDAPS certificates, add the below and uncomment (remove the #)
# Only set this option if debugging or you're absolutely sure it's required for your setup.
# If using php-fpm, you may want to restart it after changing this option to avoid instability.
depending on your setup and how you manage users in the system. You will still need to follow the setup instructions above.
```bash
-LDAP_USER_FILTER=(&(sAMAccountName=${user}))
+LDAP_USER_FILTER=(&(sAMAccountName={user}))
LDAP_VERSION=3
LDAP_ID_ATTRIBUTE=BIN;objectGUID
# Change the below to true if your AD server supports TLS and if your
Listed below are some considerations to keep in mind in regard to BookStack's OIDC implementation:
-- Only RS256 is currently supported as a token signing algorithm, Token encryption is not supported.
+- Only RS256 is currently supported as a token signing algorithm, Token encryption is not supported. This applies to both ID tokens and userinfo responses.
- Discovery covers fetching the auth & token endpoints, in addition to parsing any keys at the JWKS URI,
from the `<issuer>/.well-known/openid-configuration` endpoint.
- Issuer discovery is not supported.
# Full URL to the OIDC token endpoint
OIDC_TOKEN_ENDPOINT=https://instance.authsystem.example.com/v1/token
+
+# Full URL to the OIDC userinfo endpoint
+# Won't be used if all required tokens are provided in the ID token.
+OIDC_USERINFO_ENDPOINT=https://instance.authsystem.example.com/v1/userinfo
```
A user in BookStack will be linked to an OIDC provided account via the `sub` claim.
By default BookStack uses [dompdf](https://github.com/dompdf/dompdf) to export pages as PDF documents. The benefit of using dompdf is that it doesn't require any additional installation or setup but the rendering capabilities are somewhat limited.
-As an alternative you can use [wkhtmltopdf](http://wkhtmltopdf.org/) to generate PDF documents instead. wkhtmltopdf uses the Qt WebKit rendering engine to provide a more accurate overall result, but comes with additional security concerns to be aware of.
+As an alternative you can instead define a command to make use of external PDF rendering options that may provide more capabilities.
+
+{{<toc>}}
+
+### Export Page Size
+
+By default PDF exports are generated at an A4 size. If you'd prefer exports to be generated at "US Letter" standard sizes
+you can specify this within your `.env` like so:
+
+```bash
+# US Letter
+EXPORT_PAGE_SIZE=letter
+```
+
+### PDF Export Command
+
+Instead of using the default PHP-based default PDF rendering system, you can define a command for BookStack to use when generating
+a PDF. This enables flexibility in what program is used to create PDF exports.
+The command is set via a `EXPORT_PDF_COMMAND` option in your `.env` file, which can use the following placeholders:
+
+- `{input_html_path}` - Path to a file where BookStack will provide HTML to convert.
+- `{output_pdf_path}` - Path to a file where the command should output its PDF result.
+
+Here's an example value for this option using these placeholders:
+
+```bash
+EXPORT_PDF_COMMAND="/scripts/convert.sh {input_html_path} {output_pdf_path}"
+```
+
+Below you can find some examples using this for specific PDF generation options.
+
+**Considerations**
+
+- Security is a significant concern for this option and process. Input HTML will include user-editable data, and is not assured to be trustworthy & safe. Ideally, any networking or filesystem access would be disabled/prevented during conversion.
+- BookStack will attempt to embed required images into the HTML data as base64 data URIs to avoid external fetching.
+- BookStack will embed CSS styling into the HTML data.
+- Use of this option requires running a process from PHP, which can be considered risky and may potentially be blocked by configuration, environment and/or systems like SELinux by default.
+- BookStack sets a timeout of 15 seconds for this command to return.
+- BookStack will use the return status code of the command as an indicator of failure/success, while also checking that the output PDF was written to.
+
+#### Example: Weasyprint Command Option
+
+**Warning:** This is option is not considered secure due to potential filesystem/network access.
+
+This option uses [weasyprint](https://doc.courtbouillon.org/weasyprint/stable/) to generate PDF exports.
+
+```bash
+EXPORT_PDF_COMMAND="weasyprint {input_html_path} {output_pdf_path}"
+```
### Using wkhtmltopdf
+**Note:** As of BookStack v24.05 this option is not considered deprecated, due to the diminishing support of wkhtmltopdf.
+You can instead use the more flexible [PDF Export Command](#pdf-export-command) option detailed above.
+
Pre-compiled binaries for wkhtmltopdf can be found on the downloads page of [their website](http://wkhtmltopdf.org/downloads.html).
BookStack will check for a file named `wkhtmltopdf` at the base folder of a BookStack install. If found it will use that to render PDF exports.
If that does not exist it will check for a `WKHTMLTOPDF` variable in the `.env` file.
ALLOW_UNTRUSTED_SERVER_FETCHING=true
```
-[See our security page for more detail regarding this option](/docs/admin/security/#server-side-requests).
-
-### Export Page Size
-
-By default PDF exports are generated at an A4 size. If you'd prefer exports to be generated at "US Letter" standard sizes
-you can specify this within your `.env` like so:
-
-```bash
-# US Letter
-EXPORT_PAGE_SIZE=letter
-```
\ No newline at end of file
+[See our security page for more detail regarding this option](/docs/admin/security/#server-side-requests).
\ No newline at end of file
projects / website / commitdiff