Accessing Docker Mail Server within Another Docker Container: Mailserver Vaultwarden (Bitwarden_rs)

To enable Vaultwarden to send password reset emails, you must configure its SMTP settings to connect to a separate, dedicated Docker Mail Server container rather than an internal service. This architecture requires both containers to reside on the same Docker network so they can resolve each other by hostname. You need to update the Vaultwarden environment variables for SMTP host, port, and authentication credentials while ensuring the mail server accepts connections from your application container.

Understanding the Architecture

The title of this guide might suggest that Vaultwarden and the mail server are part of a single monolithic unit, but they are distinct services. Vaultwarden is the Rust-based implementation of Bitwarden’s API, handling user interfaces and data storage. The mail server, often provided by images like mailserver/docker-mailserver, handles the complex protocol requirements of SMTP (Simple Mail Transfer Protocol) and IMAP. Keeping these separated allows you to maintain secure email delivery without bloating the password manager container with unnecessary dependencies. For this integration to work, both containers must be able to communicate over a private network. If they are managed via docker-compose, this is handled automatically if they share the same top-level networks definition. If you are running them as standalone containers, you must explicitly attach them to a common bridge network. This ensures that when Vaultwarden attempts to connect to the mail server using the service name as the hostname, the request reaches the correct destination within the Docker daemon.

Configuring the Docker Network

Before adjusting any application settings, verify that the networking layer is correctly established. In a typical docker-compose.yml file, you should see a section at the bottom defining networks. Both the vaultwarden service and the mailserver service must be listed under the services block and assigned to the same network alias or default network. If you are using standalone containers, create a network first:

docker network create vaultwarden-net

Then, ensure both containers are attached to it. For the mail server, you may need to restart it after attaching if it was already running. This step is critical because DNS resolution inside Docker relies on the network context. Without being on the same network, the SMTP_HOST variable in Vaultwarden will fail to resolve, resulting in connection timeouts or "host not found" errors during password resets.

Setting Up Vaultwarden SMTP Environment Variables

Vaultwarden uses environment variables to configure its outgoing mail capabilities. These variables are typically defined in your .env file or directly in the docker-compose.yml under the environment key for the Vaultwarden service. You must identify the specific hostname of your mail server container. In most setups, this is simply the service name defined in your compose file, such as mailserver or smtp. The essential variables include:

• SMTP_HOST: The hostname or IP address of the mail server container.
• SMTP_PORT: Usually 587 for STARTTLS or 465 for SSL/TLS.
• SMTP_FROM: The sender email address that recipients will see.
• SMTP_USERNAME: The authenticated user account on the mail server.
• SMTP_PASSWORD: The password for that account.
• SMTP_SECURITY: Set to "starttls" or "ssl" depending on your mail server configuration.

It is crucial to use strong, unique passwords for the SMTP user account. Do not use the root administrator credentials of the mail server if avoidable; instead, create a dedicated mailbox for automated notifications. Once these variables are set, restart the Vaultwarden container to apply the changes.

Securing the Mail Server Connection

While basic connectivity is important, security is paramount when dealing with email credentials. Ensure that your mail server is configured to accept TLS connections. Most modern mail server images support STARTTLS on port 587. Configure Vaultwarden to use SMTP_SECURITY=starttls to encrypt the communication channel between the password manager and the mail server. Additionally, restrict access to the mail server's SMTP port if possible. While Docker networks provide isolation, configuring firewall rules or allowing only specific source IPs adds another layer of defense. If you are exposing the mail server to the public internet for receiving external mail, ensure that the submission port used by Vaultwarden remains internal-only or is protected by strict authentication. This prevents unauthorized entities from using your server as an open relay.

Troubleshooting Common Issues

If password resets fail, check the logs of both containers. Use docker logs vaultwarden to look for SMTP connection errors. Common issues include incorrect hostnames, wrong ports, or authentication failures. Verify that the SMTP_USERNAME matches a valid mailbox on the mail server. If you recently changed the mail server's domain configuration, ensure that Vaultwarden's SMTP_FROM address belongs to that domain. You can also test connectivity manually by executing a shell inside the Vaultwarden container and using tools like telnet or nc to ping the mail server's SMTP port. This isolates whether the issue lies with the application configuration or the underlying network connectivity. Running Additional Services with Docker Compose: A Mail Server Example provides further details on integrating multiple services efficiently. Additionally, Accessing Docker Mail Server: Vaultwarden (Bitwarden_rs) and Mailserver explores advanced configurations for these two distinct systems working together.

Frequently Asked Questions

Can I use the same container for Vaultwarden and the mail server?

No, it is not recommended to run both services in a single container due to complexity and resource management. Separating them allows you to scale and update each service independently. This modular approach also improves security by limiting the attack surface of each container.

What happens if the SMTP password contains special characters?

Special characters in passwords may cause parsing errors in environment variables. It is best to URL-encode the password or use a simpler password if the mail server allows it. Alternatively, store sensitive credentials in a .env file and ensure proper escaping in your docker-compose configuration.

How do I verify that the mail server is accepting connections from Vaultwarden?

Check the mail server logs for incoming connection requests from the Vaultwarden container's IP address. You can also use docker exec -it vaultwarden nc -zv mailserver 587 to test TCP connectivity from within the application container.

Is it safe to expose the SMTP port to the public internet?

Exposing the submission port (587) publicly is generally safe if authentication is required, but it increases exposure to brute-force attacks. It is safer to keep the submission port internal and only expose the standard SMTP port (25) or IMAP/POP3 ports if necessary for client access.

Why are my password reset emails going to spam?

Spam filtering depends on DNS records like SPF, DKIM, and DMARC configured on your mail server. Ensure these records are correctly set up for the domain used in SMTP_FROM. Additionally, verify that your mail server's reverse DNS PTR record matches the sending domain.