bookstack/website
Fork 4
Code Issues 5 Pull requests Activity

Added clarity to pdf rendering server fetching

Browse source 
As per BookStackApp/BookStack#3285
This commit is contained in:
Dan Brown 2022-02-25 13:29:47 +00:00
commit f660e561cb
Signed by: danb
GPG key ID: 46D9F943C24A2EF9
2 changed files with 12 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

18
content/docs/admin/pdf-rendering.md
View file

@ -5,29 +5,33 @@ date = "2017-01-22"
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.
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.
### Using wkhtmltopdf
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's. If that does not exist it will check for a `WKHTMLTOPDF` variable in the `.env` file. You can use this variable to set an alternate location to wkhtmltopdf:
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.
You can use the below variable in your `.env` file to set an alternate location to wkhtmltopdf:
```bash
# In .env file
WKHTMLTOPDF=/home/user/bins/wkhtmltopdf
```
If neither of those exist Dompdf will be used instead.
If neither of those exist, or if the below mentioned security option is not enabled, the default dompdf renderer will be used instead.
**Note:** as of BookStack v21.08 you'll need to also enable untrusted server fetching in your `.env` file like below.
**Note:** As of BookStack v21.08 the `ALLOW_UNTRUSTED_SERVER_FETCHING` must also be set to `true` for wkhtmltopdf to be enabled, without this dompdf will be used instead.
This change was made for security since, in many cases, wkhtmltopdf will perform fetches to external URLs which may be defined by users.
You should only enable the below option in environments where only trusted users can export content.
You should only enable the below option in environments where users & visitors are trusted.
```bash
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

1
content/docs/admin/security.md
View file

@ -207,6 +207,7 @@ cases, will log to your webserver error log files.
Some features, such as the PDF exporting, have the option to make http calls to external user-defined locations to do things
such as load images or styles. This is disabled by default but can be enabled if desired. This is required for using
WKHTMLtoPDF as your PDF export renderer.
This should only be enabled in BookStack environments where BookStack users and viewers are fully trusted.
To enable untrusted server side requests, you need to define the `ALLOW_UNTRUSTED_SERVER_FETCHING` option in your `.env` file like so: