BookStack addon in Home Assistant - mail delivery configuration.

BookStack addon in Home Assistant - mail delivery configuration.
Photo by Sharon McCutcheon / Unsplash

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.

MariaDB database via this addon is required 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, 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:


# Host, Port & Encryption mechanism to use

# Authentication details for your SMTP service

# The "from" email address for outgoing email

# The "from" name used for outgoing email

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:

  - name: MAIL_DRIVER
    value: smtp
  - name: MAIL_HOST
    value: smtp.server.tld
  - name: MAIL_PORT
    value: '587'
    value: 'null'
    value: user@domai.tld
    value: password
  - name: MAIL_FROM
    value: BookStack@domain.tld
  - name: MAIL_FROM_NAME
    value: BookStack
ssl: false
certfile: fullchain.pem
keyfile: privkey.pem
BookStack mail configuration in Home Assistant addon

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

Email confirming that mail delivery works

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