Add MAIL_PASSWORD_FILE support #5359

New Issue

OVERLORD · 2026-02-05T10:00:12+03:00

OVERLORD commented

2026-02-05 10:00:12 +03:00

Originally created by @forksnd on GitHub (Jul 15, 2025).

Describe the feature you'd like

Currently, BookStack allows adding the password for Mail server using the MAIL_PASSWORD environment variable. However, another way to provide the password is through the MAIL_PASSWORD_FILE variable set to the name of the file which contains the password. This is the method used by Docker Secrets, for example.

Essentially, if MAIL_PASSWORD_FILE is set, the program should try to read the file whose name it is set to, and use the contents as password. If MAIL_PASSWORD_FILE is not set, then it should read MAIL_PASSWORD.

Describe the benefits this would bring to existing BookStack users

It would be useful to have this method available, so that BookStack can easily integrate with setups that already use Docker Secrets to manage SMTP password.

Can the goal of this request already be achieved via other means?

Only by writing fragile wrapper scripts to be used as custom entrypoints, which is not ideal.

Have you searched for an existing open/closed issue?

I have searched for existing issues and none cover my fundamental request

How long have you been using BookStack?

1 to 5 years

Additional context

No response

Originally created by @forksnd on GitHub (Jul 15, 2025). ### Describe the feature you'd like Currently, BookStack allows adding the password for Mail server using the `MAIL_PASSWORD` environment variable. However, another way to provide the password is through the `MAIL_PASSWORD_FILE` variable set to the name of the file which contains the password. This is the method used by Docker Secrets, for example. Essentially, if `MAIL_PASSWORD_FILE` is set, the program should try to read the file whose name it is set to, and use the contents as password. If `MAIL_PASSWORD_FILE` is not set, then it should read `MAIL_PASSWORD`. ### Describe the benefits this would bring to existing BookStack users It would be useful to have this method available, so that BookStack can easily integrate with setups that already use Docker Secrets to manage SMTP password. ### Can the goal of this request already be achieved via other means? Only by writing fragile wrapper scripts to be used as custom entrypoints, which is not ideal. ### Have you searched for an existing open/closed issue? - [x] I have searched for existing issues and none cover my fundamental request ### How long have you been using BookStack? 1 to 5 years ### Additional context _No response_

OVERLORD added the 🔨 Feature Request label 2026-02-05 10:00:12 +03:00

OVERLORD commented

2026-02-05 10:00:14 +03:00

@ssddanbrown commented on GitHub (Jul 15, 2025):

Thanks @forksnd,

so that BookStack can easily integrate with setups that already use Docker Secrets to manage SMTP password.

I have no experience with docker secrets, but If you're managing things at a docker-level, can you not just pass the password (read by docker secrets) on to BookStack via an env option? Or is that not possible with docker secrets?

@ssddanbrown commented on GitHub (Jul 15, 2025): Thanks @forksnd, > so that BookStack can easily integrate with setups that already use Docker Secrets to manage SMTP password. I have no experience with docker secrets, but If you're managing things at a docker-level, can you not just pass the password (read by docker secrets) on to BookStack via an env option? Or is that not possible with docker secrets?

OVERLORD commented

2026-02-05 10:00:16 +03:00

@forksnd commented on GitHub (Jul 15, 2025):

can you not just pass the password

Not without having a custom entrypoint script, see here for an example.

I have no experience with docker secrets

Basically, you put you password in a file owned by root and not visible to anyone else. Then, docker bind-mounts the file inside the container in the /run/secrets/ directory, and the program is supposed to read the password from there (which is why its path should be passed in the MAIL_PASSWORD_FILE env var). This prevents us from putting the password directly in the compose file or a .env file which is usually readable by all users.

@forksnd commented on GitHub (Jul 15, 2025): > can you not just pass the password Not without having a custom entrypoint script, [see here for an example](https://stackoverflow.com/questions/77955182/secrets-in-compose-environment-variable-has-file-path-as-value-instead-of-its-c). > I have no experience with docker secrets Basically, you put you password in a file owned by root and not visible to anyone else. Then, docker bind-mounts the file inside the container in the `/run/secrets/` directory, and the program is supposed to read the password from there (which is why its path should be passed in the `MAIL_PASSWORD_FILE` env var). This prevents us from putting the password directly in the compose file or a `.env` file which is usually readable by all users.

OVERLORD commented

2026-02-05 10:00:19 +03:00

@ssddanbrown commented on GitHub (Jul 15, 2025):

Thanks for explaining @forksnd.
Since there's been no prior request for this it's probably not something I'd look to support, but you may be able to achieve this via our logical theme system with a simple hack, probably with a functions.php along the lines of:

<?php

use BookStack\Facades\Theme;
use BookStack\Theming\ThemeEvents;

Theme::listen(ThemeEvents::APP_BOOT, function () {
    $mailPass = file_get_contents("/run/secrets/my_secret");
    config()->set('mail.mailers.smtp.password', $mailPass);
});

@ssddanbrown commented on GitHub (Jul 15, 2025): Thanks for explaining @forksnd. Since there's been no prior request for this it's probably not something I'd look to support, but you may be able to achieve this via our [logical theme system](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/logical-theme-system.md) with a simple hack, probably with a `functions.php` along the lines of: ```php <?php use BookStack\Facades\Theme; use BookStack\Theming\ThemeEvents; Theme::listen(ThemeEvents::APP_BOOT, function () { $mailPass = file_get_contents("/run/secrets/my_secret"); config()->set('mail.mailers.smtp.password', $mailPass); }); ```

OVERLORD commented

2026-02-05 10:00:21 +03:00

@forksnd commented on GitHub (Jul 16, 2025):

I looked and MySQL also supports MYSQL_PASSWORD_FILE, while LinuxServer's MariaDB image supports it with slightly different name ("FILE__MYSQL_ROOT_PASSWORD"). But it's not of much use right now since Bookstack needs those passwords passed in as environment variable in DB_PASS anyway.

Regardless, thanks for the hack. I'll leave the issue open in case you decide to implement this in the future.

@forksnd commented on GitHub (Jul 16, 2025): I looked and MySQL also supports `MYSQL_PASSWORD_FILE`, while LinuxServer's MariaDB image supports it with slightly different name (`"FILE__MYSQL_ROOT_PASSWORD"`). But it's not of much use right now since Bookstack needs those passwords passed in as environment variable in `DB_PASS` anyway. Regardless, thanks for the hack. I'll leave the issue open in case you decide to implement this in the future.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#5359