Started v24-05 doc updates and notices

Nothing here checked over yet

diff --git a/content/blog/2024/bookstack-release-v24-05.md b/content/blog/2024/bookstack-release-v24-05.md
index c58fab27aecbc1e4d87ccb52e5f4d4c421b6c7a3..84e9afd29874fab42edd57c7378fa5c0ecd85d32 100644 (file)
--- a/content/blog/2024/bookstack-release-v24-05.md
+++ b/content/blog/2024/bookstack-release-v24-05.md
@@ -9,19 +9,24 @@ slug = "bookstack-release-v24-05"
 draft = false
 +++
 
 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**
 
 
 * [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
 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>}} -->
 
 TODO - Video
 <!-- {{<pt 8w3F4aWqH3MProMwyQBf2d>}} -->

diff --git a/content/docs/admin/installation.md b/content/docs/admin/installation.md
index 276481516666cac1b369fdc7bd939fbca34fca63..377fb6cfbc3408150141a87174f1056fa879feb2 100644 (file)
--- a/content/docs/admin/installation.md
+++ b/content/docs/admin/installation.md
@@ -27,7 +27,7 @@ Below you can find details on how to install BookStack on your own hosting. Ther
 
 BookStack has the following requirements:
 
 
 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)*.
     * 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)*.


@@ -36,7 +36,7 @@ BookStack has the following requirements:
     * Single Database *(All permissions advised since application manages schema)*
 * **Git Version Control**
     * For application of updates when following our standard process.
     * 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.
     * For installation and management of our PHP dependencies.
 * **A PHP Compatible Webserver**
     * For usage with PHP and for serving static files.

diff --git a/content/docs/admin/ldap-auth.md b/content/docs/admin/ldap-auth.md
index 91e7146b2c13896c9a2b17453633292d4bd54e07..d01fc809329bc3647b05aa7849254c0bb45ce7d2 100644 (file)
--- a/content/docs/admin/ldap-auth.md
+++ b/content/docs/admin/ldap-auth.md
@@ -33,11 +33,9 @@ LDAP_DN="cn=serviceaccount,ou=People,dc=example,dc=org"
 LDAP_PASS="my#super#secret#password543"
 
 # A filter to use when searching for users
 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.
 
 # Set the LDAP version to use when connecting to the server
 # Should be set to 3 in most cases.


@@ -69,6 +67,14 @@ LDAP_THUMBNAIL_ATTRIBUTE=jpegphoto
 # Defaults to 'false'.
 LDAP_START_TLS=false
 
 # 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.
 # 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.


@@ -91,7 +97,7 @@ BookStack does work with active directory over LDAP. You will likely need to set
 depending on your setup and how you manage users in the system. You will still need to follow the setup instructions above.
 
 ```bash
 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
 LDAP_VERSION=3
 LDAP_ID_ATTRIBUTE=BIN;objectGUID
 # Change the below to true if your AD server supports TLS and if your

diff --git a/content/docs/admin/oidc-auth.md b/content/docs/admin/oidc-auth.md
index e113bef2b6e2fa9d67b06985de8287c5878c493f..2509eaa200be3bcb396ae1e625c69672a0d74ae1 100644 (file)
--- a/content/docs/admin/oidc-auth.md
+++ b/content/docs/admin/oidc-auth.md
@@ -29,7 +29,7 @@ We have a range of videos available that can help show, for a range of identity
 
 Listed below are some considerations to keep in mind in regard to BookStack's OIDC implementation:
 
 
 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.
 - 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.


@@ -93,6 +93,10 @@ OIDC_AUTH_ENDPOINT=https://instance.authsystem.example.com/v1/authorize
 
 # Full URL to the OIDC token endpoint
 OIDC_TOKEN_ENDPOINT=https://instance.authsystem.example.com/v1/token
 
 # 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.
 ```
 
 A user in BookStack will be linked to an OIDC provided account via the `sub` claim.

diff --git a/content/docs/admin/pdf-rendering.md b/content/docs/admin/pdf-rendering.md
index 8bc22a86299ca534c1b9ce48e58af3ca19cc720a..fb3bf3cb598c562c793b6d4004b13630d42f2fb5 100644 (file)
--- a/content/docs/admin/pdf-rendering.md
+++ b/content/docs/admin/pdf-rendering.md
@@ -7,10 +7,61 @@ type = "admin-doc"
 
 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.
 
 
 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
 
 
 ### 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. 
 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. 


@@ -30,14 +81,4 @@ You should only enable the below option in environments where users & visitors a
 ALLOW_UNTRUSTED_SERVER_FETCHING=true
 ```
 
 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