bookstack/website
Fork 4
Code Issues 5 Pull requests Activity

Continued v21.12 post, Added webhooks & queues to docs

Browse source
This commit is contained in:
Dan Brown 2021-12-21 20:47:43 +00:00
commit 3c1d62098e
Signed by: danb
GPG key ID: 46D9F943C24A2EF9
9 changed files with 172 additions and 69 deletions
Download patch file Download diff file Expand all files Collapse all files

32
content/blog/bookstack-release-v21-12.md
View file

@ -29,12 +29,12 @@ BookStack can now emit webhooks! These are web requests that are emitted by Book
when someone performs an action in the system (Updates page, Creates book etc..).
Webhooks can be found by an administrator in the application settings.
!! Image of webhooks list
![Webhook list in settings](/images/2021/12/webhooks_list.png)
Webhooks can be triggered by any event that's tracked in the audit log. You can choose
specific events to trigger your webhooks or you can trigger upon any event.
!! Image of webhook create view
![Webhook from view](/images/2021/12/webhook_form.png)
When triggered, BookStack will send a HTTP POST JSON request to the provided endpoint
with a common set of details regarding the event. The general data format is shown when creating
@ -87,9 +87,7 @@ The possibilities are pretty endless.
Since webhooks need to make external HTTP requests, they have potential to slow down a system.
If you're introducing webhooks that'd be triggered we have a way to run these in the background to
prevent user experience slowdowns. Details about this can be found in the docs here.
!! TODO - Update above with link
prevent user experience slowdowns. [Details about this can be found here](/docs/admin/email-webhooks/#async-action-handling).
### Copy Entire Chapters & Books
@ -98,7 +96,7 @@ copy entire chapters or even books. Performing this action will also copy all ch
and/or pages in a single smooth action. Copy views will now show warnings to confirm
copy behavior within BookStack so the necessary considerations can be made.
!! IMAGE OF COPY VIEW
![Book copy view](/images/2021/12/copy_book.png)
These new abilities bring some great potential new workflow advancements, such as being
able to create "templated" books pre-configured with the right chapter & page structure
@ -109,7 +107,18 @@ ready to be copied out.
When creating or updating a role there are a lot of permissions to configure.
Creating a set of similar roles could be a time consuming experience.
As of v21.12 there's now a "Copy" action when viewing an existing role which
will take you to the role create view with all fields filled as per the copied role:
will take you to the role create view with all fields filled as per the copied role.
![Role copy button](/images/2021/12/copy_role.png)
### Audit Log IP Address Search
The audit log has received another update thanks to [@johnroyer](https://github.com/BookStackApp/BookStack/pull/3081).
It's now possible to search the audit log by IP address.
The search is a prefix-match so you can search using just the starting
portion if needing to search a range.
![IP address search in audit log](/images/2021/12/audit_log_search.png)
### Search API Updates
@ -140,7 +149,7 @@ run on command line via `php artisan bookstack:<command>`.
I recently produced a getting started guide for the local theme system which includes
registering custom commands:
<iframe width="560" height="315" src="https://www.youtube.com/embed/YVbpm_35crQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
<iframe width="100%" height="360" src="https://www.youtube.com/embed/YVbpm_35crQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
### Translations
@ -153,7 +162,12 @@ content up-to-date. The below are the great contributions since v21.11:
**Released in v21.12**
* Added webhooks. ([#147](https://github.com/BookStackApp/BookStack/pull/147), [#3099](https://github.com/BookStackApp/BookStack/pull/3099))
* Added ability to copy books, chapters & roles. ([#3118](https://github.com/BookStackApp/BookStack/pull/3118), [#1123](https://github.com/BookStackApp/BookStack/issues/1123))
* Added audit log IP address search. Thanks to [@johnroyer](https://github.com/BookStackApp/BookStack/pull/3081). ([#3081](https://github.com/BookStackApp/BookStack/pull/3081))
* Updated translations with latest Crowdin changes. ([#3117](https://github.com/BookStackApp/BookStack/pull/3117))
* Fixed issue where non-ascii content could break search result previews. Thanks to [@Kristian-Krastev](https://github.com/BookStackApp/BookStack/pull/3113). ([#3113](https://github.com/BookStackApp/BookStack/pull/3113))
* Fixed mismatched password validation rules across the application. ([#2237](https://github.com/BookStackApp/BookStack/issues/2237))
**Released in v21.11.1 through v21.11.3**

59
content/docs/admin/email-config.md
View file

@ -1,59 +0,0 @@
+++
title = "Email Configuration"
description = "Configuring BookStack to send email"
date = "2020-03-14"
type = "admin-doc"
slug = "email-config"
+++
BookStack sends out emails for a range of purposes such as email-address confirmation & "forgot password" flows.
The following mechanisms for sending mail are supported:
1. SMTP
3. Sendmail (Linux sendmail)
## SMTP
To get up and running with SMTP you will need to add, or set, the following variables in your `.env` file:
```bash
MAIL_DRIVER=smtp
# Host, Port & Encryption mechanism to use
MAIL_HOST=smtp.provider.tld
MAIL_PORT=465
MAIL_ENCRYPTION=tls
# Authentication details for your SMTP service
MAIL_USERNAME=user@provider.tld
MAIL_PASSWORD=onlyifneeded
# The "from" email address for outgoing email
MAIL_FROM=noreply@yourdomain.tld
# The "from" name used for outgoing email
MAIL_FROM_NAME=BookStack
```
## Sendmail
The `sendmail` drivers uses the sendmail application on the host system. It will call `/usr/sbin/sendmail -bs`.
To enable this option you can set the following in your `.env` file:
```bash
MAIL_DRIVER=sendmail
# The "from" email address for outgoing email
MAIL_FROM=noreply@yourdomain.tld
# The "from" name used for outgoing email
MAIL_FROM_NAME=BookStack
```
## Debugging
You can follow the instructions provided in the [debugging documentation page](/docs/admin/debugging/)
to help gain more details about issues you may come across. Within the Settings > Maintenance area of
BookStack you can find a "Send a Test Email" action which provides a quick & easy way to send emails
after changing your configuration. This action will also attempt to capture any errors thrown and display them.

133
content/docs/admin/email-webhooks.md Normal file
View file

@ -0,0 +1,133 @@
+++
title = "Email & Webhooks"
date = "2021-12-21"
type = "admin-doc"
slug = "email-webhooks"
aliases = ["email-config"]
+++
Within BookStack email is used in various ways relating to user management & authentication.
Outgoing webhooks are available as a mechanism to extend BookStack or notify in an event-driven manner.
- [Email Configuration](#email-configuration)
- [Outgoing Webhooks](#outgoing-webhooks)
- [Async Action Handling](#async-action-handling)
---
### Email Configuration
BookStack sends out emails for a range of purposes such as email-address confirmation & "forgot password" flows.
Both SMTP and Sendmail (Linux Sendmail) are supported email mechanisms.
#### SMTP
To get up and running with SMTP you will need to add, or set, the following variables in your `.env` file:
```bash
MAIL_DRIVER=smtp
# Host, Port & Encryption mechanism to use
MAIL_HOST=smtp.provider.tld
MAIL_PORT=465
MAIL_ENCRYPTION=tls
# Authentication details for your SMTP service
MAIL_USERNAME=user@provider.tld
MAIL_PASSWORD=onlyifneeded
# The "from" email address for outgoing email
MAIL_FROM=noreply@yourdomain.tld
# The "from" name used for outgoing email
MAIL_FROM_NAME=BookStack
```
#### Sendmail
The `sendmail` drivers uses the sendmail application on the host system. It will call `/usr/sbin/sendmail -bs`.
To enable this option you can set the following in your `.env` file:
```bash
MAIL_DRIVER=sendmail
# The "from" email address for outgoing email
MAIL_FROM=noreply@yourdomain.tld
# The "from" name used for outgoing email
MAIL_FROM_NAME=BookStack
```
#### Debugging Email
You can follow the instructions provided in the [debugging documentation page](/docs/admin/debugging/)
to help gain more details about issues you may come across. Within the "Settings > Maintenance" area of
BookStack you can find a "Send a Test Email" action which provides a quick & easy way to send emails
after changing your configuration. This action will also attempt to capture any errors thrown and display them.
---
### Outgoing Webhooks
Webhooks can be configured in the "Settings > Webhooks" area of your BookStack instance.
An example of the POST data format is shown when creating or editing a webhook.
The running on webhooks can slow down a system due to the required additional processing time.
See the [async action handling](#async-action-handling) section below to details on running webhooks
in a background process to improve performance.
---
### Async Action Handling
Actions like sending email or triggering webhooks are done synchronously by default within BookStack which can
slow down page loading when those actions are triggered. These actions can instead be processed asynchronously
so they're handled in the background to prevent slowing down the request. This requires a config change
and a queue worker process to handle these background jobs:
#### Config Change
Within your `.env` file add or update (if already existing) the following option then save the file.
```bash
QUEUE_CONNECTION=database
```
#### Queue Worker Process
The queue work process can be run via the following command from your BookStack installation directory:
```bash
php artisan queue:work --sleep=3 --tries=3
```
Ideally this needs to be ran continuously. The method of doing this may depend on your operating system
and personal software preferences. On many modern Linux systems systemd is an appropriate method.
The below unit file example can be used with systemd to run this process. Note, this is suited to
Ubuntu 20.04 setups that have used our installation script. Details may need tweaking for other systems.
```bash
[Unit]
Description=BookStack Queue Worker
[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/bookstack/artisan queue:work --sleep=3 --tries=1 --max-time=3600
[Install]
WantedBy=multi-user.target
```
To configure systemd (On a Ubuntu 20.04 system) with the above unit you'd typically:
- Create a new `/etc/systemd/system/bookstack-queue.service` file containing the above content.
- Run `systemctl daemon-reload` to discover the new service.
- Run `systemctl enable bookstack-queue.service` to ensure the service starts at (re)boot.
- Run `systemctl start bookstack-queue.service` to start the queue service.
Note: you may need to run the above commands with `sudo` if not acting as a privileged user.
You can then use `systemctl status bookstack-queue.service` to check the status of the queue worker.

BIN
static/images/2021/12/audit_log_search.png (Stored with Git LFS) Normal file
View file

Binary file not shown.

BIN
static/images/2021/12/copy_book.png (Stored with Git LFS) Normal file
View file

Binary file not shown.

BIN
static/images/2021/12/copy_role.png (Stored with Git LFS) Normal file
View file

Binary file not shown.

BIN
static/images/2021/12/webhook_form.png (Stored with Git LFS) Normal file
View file

Binary file not shown.

BIN
static/images/2021/12/webhooks_list.png (Stored with Git LFS) Normal file
View file

Binary file not shown.

2
themes/bookstack/layouts/partials/menu_admin_docs.html
View file

@ -24,7 +24,7 @@
<h4>Configuration</h4>
<ul>
<li><a href="/docs/admin/email-config">Email Configuration</a></li>
<li><a href="/docs/admin/email-webhooks">Email & Webhooks</a></li>
<li><a href="/docs/admin/visual-customisation">Visual Customisation</a></li>
<li><a href="/docs/admin/language-config">Language &amp; Locale</a></li>
<li><a href="/docs/admin/upload-config">File Uploads</a></li>