BookStack addon in Home Assistant - mail delivery configuration.

I just discovered this awesome self-hosted app called BookStack while searching for something I can use to store all knowledge and instructions for myself from various of systems, networks, scripts etc.

Luckily there is addon in Home Assistant. So installation is just as simple as few clicks. Worth to note, that BookStack requires MariaDB database, so MariDB addon is also required when using in Home Assistant.

After installing BookStack just run it and it will create database for itself via MariaDB addon. Thats is - login with default user and password on IP of your HA and port 2665, and change it for something uniq for yourself. Default login is admin@admin.com, and password is 'password'.

While editing and managing all shelf and books are intuitive, I couldn't find any settings for mail delivery in GUI. There is only option to send test email which obviously didn't work.

Quick check in BookStack documentation revealed that mail delivery configuration is done in .env file by defining variables and values. Here is revelent part from documenatation:

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

However using addon in HA doesn't give access to .env file or at least not in easy way of tinkering with docker image of addon.

To be able to use this configuration we need to edit configuration in configuration tab of plugin. There is something called  envvars: [] at the beginning and under it we need to put variables from documentation. First I just put all variables as is between brackets and of course nothing worked, because config didn't parsed.

Config requires to be valid yaml, so spacing is important, and every variable and its value have to be in separate line. Not to mention proper quoting numbers and if you don't use tls (as I do in local deliverying) you need to set it to 'null' instead  of just delete it from config.

So here is my part of config with correct formatiing:

envvars:
  - name: MAIL_DRIVER
    value: smtp
  - name: MAIL_HOST
    value: smtp.server.tld
  - name: MAIL_PORT
    value: '587'
  - name: MAIL_ENCRYPTION
    value: 'null'
  - name: MAIL_USERNAME
    value: user@domai.tld
  - name: MAIL_PASSWORD
    value: password
  - name: MAIL_FROM
    value: BookStack@domain.tld
  - name: MAIL_FROM_NAME
    value: BookStack
ssl: false
certfile: fullchain.pem
keyfile: privkey.pem

After restartingplugin I was able to send test email to my user email address.

And of course, this piece of knowledge have to be written into newly created Book of Home Assistant documentation ;)