Bookstack Customization & Setup Guide

Setup your Own Wiki!

Getting Started

Getting Started

Step-by-Step Guide: Setup Bookstack

GitHub-logo.pngicon.png

BookStack is a simple and powerful documentation platform that can be easily deployed using Docker. In this guide, we will set up BookStack on a 3-node Docker Swarm cluster with data stored in a GlusterFS volume. This setup will also utilize Traefik as a reverse proxy with Let's Encrypt for SSL certificates. For more information on setting up Traefik, check out this guide.

Step 1: Create Directories for BookStack Data

Before starting the BookStack containers, you need to create directories where BookStack will store its data. Since we're using GlusterFS to manage our distributed storage, you'll need to create these directories on the shared GlusterFS mount on each node.

mkdir /mnt/glustermount/data/bookstack_data
mkdir /mnt/glustermount/data/bookstack_data/app
mkdir /mnt/glustermount/data/bookstack_data/db

Step 2: Set Up the Docker Compose File

Below is the docker-compose.yml file that defines the BookStack application and its database (MariaDB). This file is customized to work with GlusterFS for data storage, Traefik for reverse proxy management, and Let's Encrypt for automatic SSL certificates.

version: "3.7"

services:
  bookstack:
    image: linuxserver/bookstack:arm64v8-24.05.3  # BookStack Docker image for ARMv8
    container_name: bookstack
    environment:
      - APP_URL=https://YOUR-APP-URL.tld  # Set your public-facing URL here
      - TZ=Europe/Zurich  # Set your timezone
      - DB_HOST=192.168.0.200  # Set the host IP where MariaDB is running
      - DB_PORT=3306  # MySQL port
      - DB_DATABASE=${BOOKSTACK_DATABASE}  # Name of the BookStack database
      - DB_USERNAME=${BOOKSTACK_MYSQL_USER}  # MySQL username for BookStack
      - DB_PASSWORD=${BOOKSTACK_MYSQL_PASSWORD}  # MySQL password for BookStack
    volumes:
      - /mnt/glustermount/data/bookstack_data/app:/config  # Mount GlusterFS for BookStack app data
    ports:
      - 6875:80  # Expose port 80 for web access
    restart: unless-stopped  # Restart the container unless it is manually stopped
    depends_on:
      - bookstack_db  # BookStack depends on the MariaDB container
    networks:
     - management_net  # Management network for internal communication
    deploy:
      mode: replicated  # Run BookStack in replicated mode in Docker Swarm
      replicas: 1  # Set the number of replicas (in this case, 1)
      labels:
        - 'traefik.enable=true'  # Enable Traefik for this service
        - 'traefik.http.routers.bookstack.rule=Host(`YOUR-APP-URL.tld`)'  # Set Traefik rule to use the public URL
        - 'traefik.http.routers.bookstack.entrypoints=websecure'  # Use the "websecure" entry point (HTTPS)
        - 'traefik.http.routers.bookstack.tls.certresolver=leresolver'  # Use Let's Encrypt resolver for TLS
        - 'traefik.http.services.bookstack.loadbalancer.server.port=80'  # BookStack uses port 80 internally

  bookstack_db:
    image: mariadb:latest  # MariaDB image for the database
    container_name: bookstack_db
    environment:
      - TZ=Europe/Zurich  # Set your timezone
      - MYSQL_ROOT_PASSWORD=${BOOKSTACK_PASSWORD}  # Root password for MariaDB
      - MYSQL_DATABASE=${BOOKSTACK_DATABASE}  # Database name for BookStack
      - MYSQL_USER=${BOOKSTACK_MYSQL_USER}  # MySQL username for BookStack
      - MYSQL_PASSWORD=${BOOKSTACK_MYSQL_PASSWORD}  # MySQL password for BookStack
    volumes:
      - /mnt/glustermount/data/bookstack_data/db:/var/lib/mysql  # Mount GlusterFS for database data
    ports:
      - 3306:3306  # Expose port 3306 for MySQL access
    restart: unless-stopped  # Restart the container unless manually stopped
    deploy:
      mode: replicated  # Run MariaDB in replicated mode in Docker Swarm
      replicas: 1  # Set the number of replicas (in this case, 1)

networks:
  management_net:
    external: true  # External management network
Explanation of Key Lines in the Docker Compose File:
Composefile without Comments 
version: "3.7"

services:
  bookstack:
    image: linuxserver/bookstack:arm64v8-24.05.3
    container_name: bookstack
    environment:
      - APP_URL=https://YOUR-APP-URL.tld
      - TZ=Europe/Zurich
      - DB_HOST=192.168.0.200
      - DB_PORT=3306
      - DB_DATABASE=${BOOKSTACK_DATABASE}
      - DB_USERNAME=${BOOKSTACK_MYSQL_USER}
      - DB_PASSWORD=${BOOKSTACK_MYSQL_PASSWORD}
    volumes:
      - /mnt/glustermount/data/bookstack_data/app:/config
    ports:
      - 6875:80
    restart: unless-stopped
    depends_on:
      - bookstack_db
    networks:
     - management_net
    deploy:
      mode: replicated
      replicas: 1
      labels:
        - 'traefik.enable=true'
        - 'traefik.http.routers.bookstack.rule=Host(`YOUR-APP-URL.tld`)'
        - 'traefik.http.routers.bookstack.entrypoints=websecure'
        - 'traefik.http.routers.bookstack.tls.certresolver=leresolver'
        - 'traefik.http.services.bookstack.loadbalancer.server.port=80'

  bookstack_db:
    image: mariadb:latest
    container_name: bookstack_db
    environment:
      - TZ=Europe/Zurich
      - MYSQL_ROOT_PASSWORD=${BOOKSTACK_PASSWORD}
      - MYSQL_DATABASE=${BOOKSTACK_DATABASE}
      - MYSQL_USER=${BOOKSTACK_MYSQL_USER}
      - MYSQL_PASSWORD=${BOOKSTACK_MYSQL_PASSWORD}
    volumes:
      - /mnt/glustermount/data/bookstack_data/db:/var/lib/mysql
    ports:
      - 3306:3306
    restart: unless-stopped
    deploy:
      mode: replicated
      replicas: 1

networks:
  management_net:
    external: true

 

Additional Environment Variables

Step 4: Deploy BookStack

To deploy the stack, navigate to the directory where you saved the docker-compose.yml file and run the following command:

docker stack deploy -c docker-compose.yml bookstack

Or run your Stack in Portainer WebGUI.

This command will deploy both BookStack and the MariaDB container on your Docker Swarm cluster.

Step 5: Access BookStack


Additional Notes

Customize Bookstack

Customize Bookstack

Set Darkmode as Default

If you want to set your Wiki to Darkmode as Default for every user entering the Website you need to adjust the Enviroment Variable APP_DEFAULT_DARK_MODE=true in your docker-compse.yaml file or your Portainer Stack Editor.

You can also check out this Article for more Environment Variables :)


Customize Bookstack

Set Default Chapter-Toggle


GitHub-logo.pngI experienced that it annoys me alot that you always need to Open the Drop-Down from each Chapter.

Which looks like this:

2024-09-08 17_53_48-CrosshairX.png

Enter Custom Code

So i found a Way on how to set a Default to always toggle those Chapter open.
Basicly you only need to open the Bookstack "Settings-Page" from your Wiki and then open the "Customization" Tab, scroll to the Bottom of the Page and insert the following Code into the "Custom Code Section":

<style>
    .chapter-contents-toggle {
        display: none !important;
    }
    .inset-list {
        display: block !important;
    }
</style>

Your Result would then look like this :)

2024-09-08 17_54_59-GlusterFS & Keepalived... _ Knowledge Base - Brave.png

Customize Bookstack

Add Custom Links into Header-Menu

free-reddit-logo-icon-2436-thumb.pngIf you want to add Custom Links to your Bookstack Navigationbar / Header-Menu you need to use the
Settings-Page from your Bookstack.

As Default it would look like this:

2024-09-08 18_09_56-Editing Page Add Custom Links into ... _ Knowledge Base - Brave.png


Lets Say you want to add a "Buy me a Coffee" Link for People to Support your work or whatever else you need to open the Bookstack "Settings-Page" from your Wiki and then open the "Customization" Tab, scroll to the Bottom of the Page and insert the following Code into the "Custom Code Section":

Please change the Icon and the Link to your Website ;)

The Result would look like this:

2024-09-08 18_12_52-Editing Page Add Custom Links into ... _ Knowledge Base - Brave.png

Customize Bookstack

Add 3rd Party Authentication (Google, Twitch etc.)

icon.png

BookStack supports third-party authentication, allowing users to log in with services like Google, GitHub, Twitter, and others. By default, these services are disabled, but you can enable them by configuring the necessary credentials from each external service.

This guide will walk you through setting up third-party authentication, focusing on the most popular services: Google, GitHub, Twitter, Facebook, Slack, AzureAD, Okta, GitLab, Twitch, and Discord.

Step 1: Enable Automatic Registration (Optional)

If you want to auto-register users when they log in via a third-party service, add the following option to your .env file or to your docker-compose.yaml:

{SERVICE}_AUTO_REGISTER=true

For example, if you're setting up Google authentication:

GOOGLE_AUTO_REGISTER=true

This will allow users to register through third-party login services even if general registration is disabled.

Step 2: Enable Automatic Email Confirmation (Optional)

You can also enable automatic email confirmation, skipping the confirmation step for trusted third-party login services:

{SERVICE}_AUTO_CONFIRM_EMAIL=true

For example, for Google:

GOOGLE_AUTO_CONFIRM_EMAIL=true

Step 3: Configure Individual Third-Party Services


Google Authentication

    1. Open the Google Developers Console.
    2. Create a new project (May have to wait a short while for it to be created).
    3. In ‘API and Services’ go to the ‘OAuth consent screen’ section and enter a product name (‘BookStack’ or your custom set name) along with any other required details until you can save your consent screen.
    4. Now in the ‘API and Services’ > ‘Credentials’ section click ‘Create Credentials’ > ‘OAuth client ID’.
    5. Choose an application type of ‘Web application’ and enter the following urls under ‘Authorized redirect URIs’, changing https://example.com to your own domain where BookStack is hosted:
      • https://example.com/login/service/google/callback
      • https://example.com/register/service/google/callback
    6. Hit ‘Create’ then take note of the ‘Client ID’ and ‘Client secret’ which you’ll use in the next step.
    7. Add or set the following items in your .env file like so:
      # Replace the '{client_id}' and '{client_secret}' below with your Google Client ID and Client secret
GOOGLE_APP_ID={client_id}
GOOGLE_APP_SECRET={client_secret}

Users can now register and log in using their Google accounts.

 

 

GitHub Authentication

  1. While logged in, open up your GitHub developer applications.
  2. Click ‘Register new application’.
  3. Enter an application name (‘BookStack’ or your custom set name) and a link to your app instance under ‘Homepage URL’. The ‘Authorization callback URL’ can be the root (homepage) URL for your BookStack instance. Once those details are set, select ‘Register application’.
  4. A ‘Client ID’ and a ‘Client Secret’ value will be shown. Add or set the following items in your BookStack .env file like so:
    # Replace the '{client_id}' and '{client_secret}' below with your GitHub Client ID and Client secret
GITHUB_APP_ID={client_id}
GITHUB_APP_SECRET={client_secret}

Users can now log in with their GitHub accounts.

Twitter Authentication

Before creating a Twitter application for signing in, you will need to have signed up and be approved on the Twitter Developer site. Part of this will require describing your use of the API.

  1. Go to your Twitter Developer Portal, after being approved by twitter as described above. Navigate to ‘Projects and Apps’ > ‘Overview’ and under ‘Standalone Apps’ click ‘Create App’.
  2. Enter an application name and save/continue to the next step.
  3. You’ll now be shown some keys and tokens. Copy out the shown ‘API key’ and ‘API secret key’ values for the next step.
  4. Within your BookStack .env file add in extra options for your token and secret like so:
    # Replace the below '{api_key}' and '{api_secret}' with your Twitter API key and API secret
TWITTER_APP_ID={api_key}
TWITTER_APP_SECRET={api_secret}
    Back within the Twitter developer dashboard, find your new standalone app and click on ‘App Settings’ then click on edit within the ‘Authentication settings’ section.

  1. Enable the ‘3-legged OAuth’ and ‘Request email address from users’ options.
  2. Enter the following URLs under ‘Callback URLs’, changing https://example.com to your own domain where BookStack is hosted:
    • https://example.com/login/service/twitter/callback
    • https://example.com/register/service/twitter/callback
  3. Fill in any remaining required URLs then click save.

Users can now log in with their Twitter accounts.

Facebook Authentication

  1. Navigate to the Facebook developers page then go ‘My Apps’ -> ‘Add a New App’.
  2. Enter an app name (‘BookStack login’ or something custom) and contact email then continue.
  3. In your new app select ‘Add Product’ on the left sidebar then choose ‘Facebook Login’ by clicking the ‘Get Started’ button. Select the ‘Web’ option if asked to choose a platform.
  4. Enter the your base BookStack url into the ‘Site URL’ box and save.
  5. On the left sidebar again go to ‘Facebook Login’ -> ‘Settings’.
  6. Enter the following URLs under ‘Valid OAuth Redirect URIs’, changing https://example.com to your own domain where BookStack is hosted:
    • https://example.com/login/service/facebook/callback
    • https://example.com/register/service/facebook/callback
  7. Navigate back to the app ‘Dashboard’ in the sidebar to find your app id and secret. Add or set these to your .env file like so:
    # Replace the below '{app_id}' and '{app_secret}' with your Facebook app ID and secret
FACEBOOK_APP_ID={app_id}
FACEBOOK_APP_SECRET={app_secret}

Users can now log in with their Facebook accounts.

Slack Authentication

  1. Go to the Slack apps page and select ‘Create An App’, then ‘From scratch’ when prompted.
  2. Enter an app name (‘BookStack login’ or something custom) and your workspace then select “Create App”.
  3. Within an “App Credentials” section, you should find your client ID and secret. Copy these details and add them as new variables in your .env file like so:
    # Replace the below '{client_id}' and '{client_secret}' with your Slack client ID and secret
SLACK_APP_ID={client_id}
SLACK_APP_SECRET={client_secret}
  4. In your slack app go to ‘OAuth & Permissions’, find the ‘Redirect URLs’ section then ‘Add New Redirect URL’. Enter your BookStack base URL then ‘Add’ before pressing ‘Save URLs’.

Users can now log in with their Slack accounts.

AzureAD (Microsoft) Authentication

Note: If you intend all users to access your instance via Azure, then using an alternative primary authentication option like OIDC or SAML 2.0 will provide a better user experience while having more features like auto-login and group sync. A video guide for setting up OIDC with AzureAD can be found here.

  1. Login to your your azure portal and navigate to the ‘Azure Activity Directory’ area.
  2. Under ‘Manage > App registrations’ select ‘New application registration’.
  3. Enter a name (‘BookStack’). Set the ‘Redirect URI’ to the “Web” platform with the value set to the following, replacing ‘https://example.com/' with your base BookStack url:
    • https://example.com/login/service/azure/callback
  4. Once created, View the application ‘Overview’ page and note the ‘Application (client) ID’ and ‘Directory (tenant) ID’ values. These are the APP_ID and TENANT values for step 9.
  5. Within your application in azure, Navigate to ‘Certificates & secrets’ then choose ‘New client secret’.
  6. Enter any description you want and set an expiry duration. Then click ‘Save’.
  7. Copy the string of characters under ‘Value’. This is the APP_SECRET value for step 9 and is only shown once.
  8. Navigate to ‘API permissions’ for your app. You should already have a “Microsoft Graph” > “User.Read” permission assigned. If not choose ‘Add a permission’. Find the ‘Microsoft Graph’ option within this, then select ‘Delegated permissions’ then find & select the ‘User.Read’ permission. Then select ‘Add permissions’ at the bottom of the page.
  9. Copy these details and add them as new variables in your .env file like so:
    # Replace the below '{APP_ID}', '{APP_SECRET}' and '{TENANT}' values with your Azure APP_ID and APP_SECRET and TENANT
AZURE_APP_ID={APP_ID}
AZURE_APP_SECRET={APP_SECRET}
AZURE_TENANT={TENANT}

Users can now log in with their AzureAD accounts.

Okta Authentication

Note: If you intend all users to access your instance via Okta, then using an alternative primary authentication option like OIDC or SAML 2.0 will provide a better user experience while having more features like auto-login and group sync.

  1. Login to Okta and, once logged in, Note the current URL. This is used for the ‘base_url’ in step 6.
  2. Navigate to the Admin panel then ‘Applications’ then select ‘Add Application’. Then select ‘Create New App’ on the left.
  3. For the ‘Platform’ choose ‘Web’. For the ‘Sign on method’ choose ‘OpenID Connect’ then click ‘Create’.
  4. Give the app a name such as ‘BookStack’ or ‘Our documentation’. Under the ‘Login redirect URIs’ option add both of the below URLs, Changing https://example.com to the base URL of your BookStack instance:
    • https://example.com/login/service/okta/callback
    • https://example.com/register/service/okta/callback
  5. Save and scroll down to the ‘Client Credentials’ area. Copy the ‘Client ID’ and ‘Client secret’ values for the next step.
  6. Copy these details and add them as new variables in your .env file like so:
    # Replace the below '{client_id}' and '{client_Secret}' with your Okta client ID and secret
OKTA_APP_ID={client_id}
OKTA_APP_SECRET={client_secret}
# Replace the '{base_url}' below with the URL from step 1
# but with everything after the domain (okta.com) removed.
OKTA_BASE_URL={base_url}

Users can now log in with their Okta accounts.

Twitch Authentication

To allow Twitch sign-in you’ll first need to create an application from the Twitch developer site. Here’s the process:

  1. Login into the Twitch developer website.
  2. Navigate to your ‘Dashboard’ then ‘Apps’ and select ‘Register Your Application’.
  3. Set a name to identify the application, such as ‘BookStack Authentication’, and in the ‘OAuth Redirect URI’ input add the below URL, Changing https://example.com to the base URL of your BookStack instance:
    • https://example.com/login/service/twitch/callback
  4. Under the ‘Application Category’ option select ‘Website Integration’ then hit ‘Register’.
  5. Click the ‘New Secret’ button and accept the prompt that appears. You should now see both a ‘Client ID’ and ‘Client Secret’ value which you’ll use in the next step.
  6. Copy the below details and add them as new variables in your .env file like so:
    # Replace the below '{client_id}' and '{client_secret}' with your Twitch client ID and secret values.
TWITCH_APP_ID={client_id}
TWITCH_APP_SECRET={client_secret}

Users can now log in with their Twitch accounts.

Discord Authentication

To allow Discord sign-in you’ll first need to create an application on the Discord developer site. Here’s the process:

  1. Login into the Discord developer website.
  2. Select ‘Create an application’.
  3. Set a name to identify the application, such as ‘BookStack Authentication’, and save.
  4. In the sidebar, Open the OAuth2 settings for your application and add a redirect. Input the below URL, Changing https://example.com to be the base URL of your BookStack instance then save:
    • https://example.com/login/service/discord/callback
  5. Back in the ‘General Information’ section find the ‘Client ID’ and ‘Client Secret’ values which you’ll use in the next step.
  6. Copy the below details and add them as new variables in your .env file like so:
    # Replace the below '{client_id}' and '{client_secret}' with your Discord client ID and secret values.
DISCORD_APP_ID={client_id}
DISCORD_APP_SECRET={client_secret}

Users can now log in with their Discord accounts.

Backups, SMTP Mail & Webhooks


Backups, SMTP Mail & Webhooks

Create & Restore Backups Guide

icon.pngWhile BookStack does not currently have a built-in way to backup and restore content, it can usually be done via the command line with relative ease. The below commands are based on using Ubuntu. If you are using a different operating system you may have to alter these commands to suit.

Backup

There are two types of content you need to backup: Files and database records.

Database

The easiest way to backup the database is via mysqldump:

# Syntax
## Only specify the `-p` option if the user provided has a password
mysqldump -u {mysql_user} -p {database_name} > {output_file_name}


# Example
mysqldump -u benny bookstack > bookstack.backup.sql

If you are using MySQL on Ubuntu, and are using the root MySQL user, you will likely have to run the command above with sudo:

sudo mysqldump -u root bookstack > bookstack.backup.sql

The resulting file (bookstack.backup.sql in the examples above) will contain all the data from the database you specified. Copy this file to somewhere safe, ideally on a different device.

Files

Below is a list of files and folders containing data you should back up. The paths are shown relative to the root BookStack folder.

Alternatively you could backup up your whole BookStack folder but only the above contain important instance-specific data by default.

The following command will create a compressed archive of the above folders and files:

tar -czvf bookstack-files-backup.tar.gz .env public/uploads storage/uploads themes

The resulting file (bookstack-files-backup.tar.gz) will contain all your file data. Copy this to a safe place, ideally on a different device.

 

Automatic Backup Script

backupscript.sh 
#!/bin/bash

# Directory to store backups within
# Should not end with a slash and not be stored within 
# the BookStack directory
BACKUP_ROOT_DIR="$HOME"

# Directory of the BookStack install
# Should not end with a slash.
BOOKSTACK_DIR="/var/www/bookstack"

# Get database options from BookStack .env file
export $(cat "$BOOKSTACK_DIR/.env" | grep ^DB_ | xargs)

# Create an export name and location
DATE=$(date "+%Y-%m-%d_%H-%M-%S")
BACKUP_NAME="bookstack_backup_$DATE"
BACKUP_DIR="$BACKUP_ROOT_DIR/$BACKUP_NAME"
mkdir -p "$BACKUP_DIR"

# Dump database to backup dir using the values
# we got from the BookStack .env file.
mysqldump --single-transaction \
 --no-tablespaces \
 -u "$DB_USERNAME" \
 -p"$DB_PASSWORD" \
 "$DB_DATABASE" > "$BACKUP_DIR/database.sql"

# Copy BookStack files into backup dir
cp "$BOOKSTACK_DIR/.env" "$BACKUP_DIR/.env"
cp -a "$BOOKSTACK_DIR/storage/uploads" "$BACKUP_DIR/storage-uploads"
cp -a "$BOOKSTACK_DIR/public/uploads" "$BACKUP_DIR/public-uploads"

# Create backup archive
tar -zcf "$BACKUP_DIR.tar.gz" \
 -C "$BACKUP_ROOT_DIR" \
 "$BACKUP_NAME"

# Cleanup non-archive directory
rm -rf "$BACKUP_DIR"

echo "Backup complete, archive stored at:"
echo "$BACKUP_DIR.tar.gz"

 

 

Restore

If you are restoring from scratch follow the installation instructions first to get a new BookStack instance set-up but do not run the php artisan migrate installation step when installing BookStack. You may need to comment this command out if using an installer script.

If you are using a docker-container-based set-up, restore the database before running the BookStack container. An example of the process using a linuxserver.io-based docker-compose setup can be seen in our video here.

Database

To restore the database you simply need to execute the sql in the output file from the mysqldump you performed above. To do this copy your database SQL backup file onto the BookStack or database host machine and run the following:

# Syntax
mysql -u {mysql_user} -p {database_name} < {backup_file_name}
## Only specify the -p if the user provided has a password

# Example
mysql -u benny -p bookstack < bookstack.backup.sql

# If using the root user on Ubuntu you may
# have to run the above with root permissions via sudo:
sudo mysql -u root bookstack < bookstack.backup.sql

If you are restoring to a new version of BookStack you will have to run php artisan migrate after restore to perform any required updates to the database.

Files

To restore the files you simply need to copy them from the backup archive back to their original locations. If you created a compressed bookstack-files-backup.tar.gz archive as per the backup instructions above you can simply copy that file to your BookStack folder then run the following command:

tar -xvzf bookstack-files-backup.tar.gz

If you get errors during the above command it may be due to permissions. Change permissions so you can write to the restore locations.

After a backup of the files you should reset the permissions to ensure any write-required locations are writable by the server. The locations required for this can be found in the installation instructions.

Configuration (.env File)

During a restore, you may end up merging various configuration options between your old and new instance .env files, to get things working for the new environment. For example, it’s common to use the old .env settings for most things but use database settings from the .env file of a newly created instance.

One thing to be aware of is that you should use the APP_KEY value of the old .env file since this is used for various features like the encryption of multi-factor authentication credentials. Changing the APP_KEY may cause such features to break.

URL Changes

If you are restoring into an environment where BookStack will run on a different URL, there are a couple of things you’ll need to do after restoring everything:

If you migrated web-server configuration files, you may also need to tweak those to correctly use the new URL.

Backups, SMTP Mail & Webhooks

Setup Email Configuration for Bookstack

icon.png

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 or docker-compose.yaml:

MAIL_DRIVER=smtp

# SMTP server host address
MAIL_HOST=smtp.provider.tld

# SMTP server port
# Using port 465 will force connections to be via TLS
MAIL_PORT=587

# Connection encryption to use
# Valid values are: tls, null
# Using 'tls' will require either TLS or STARTTLS to be used.
# When using 'null' STARTTLS will still be attempted if announced
# as supported by your SMTP server.
# Using port 465 above will force connections to be via TLS.
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
Connection TLS/SSL Certificate Verification

In some cases your SMTP server may be using a private/self-signed TLS/SSL certificate that would usually fail certificate verification. In these cases its common for that certificate (Or its CA) to be added to the BookStack’s host trusted certificate database. If that’s not possible, you can alternatively disable SSL/TLS certificate verification for mail sending by adding this setting to your .env file or docker-compose.yaml:

# Verify SSL/TLS certificates during SMTP sending
# WARNING: Disabling verification using a 'false' value 
# can make you vulnerable to MITM attacks
MAIL_VERIFY_SSL=false

Sendmail

The sendmail drivers uses the sendmail application on the host system. By default it will call /usr/sbin/sendmail -bs although this is configurable.
To enable this option you can set the following in your .env file or docker-compose.yaml:

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

# The command to use for calling sendmail
MAIL_SENDMAIL_COMMAND="/usr/sbin/sendmail -bs"

Debugging Email

You can follow the instructions provided in the debugging documentation page 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.

Backups, SMTP Mail & Webhooks

Webhooks

https://foss.video/w/xu4T7mafyLqkLU1VTgNaCV