How to Install with Docker Compose

This guide describes how to install docker-mailserver using Docker Compose.

If you are setting up docker-mailserver for the first time, the Getting Started tutorial provides a step-by-step walkthrough that covers these same steps with more explanation.

Prerequisites

Docker and Docker Compose installed on the host
A domain name
Root or sudo access on the host

Steps

1. Configure environment variables

Copy the example environment file and edit .env:

cp .env.dist .env

Set at least MYSQL_PASSWORD, REDIS_PASSWORD, CONTROLLER_PASSWORD, and DOVEADM_API_KEY. See Environment variables reference.

2. Pull images

bin/production.sh pull

3. Start services

bin/production.sh up -d --wait

4. Run setup wizard

bin/production.sh run --rm web setup.sh

Follow the wizard to create your first account and admin user.

5. Access the management interface

Management: http://127.0.0.1:81/manager/
Webmail: http://127.0.0.1:81/webmail/

Post-installation

Configure DNS (MX, SPF, DKIM, DMARC). See How to configure DNS and DNS records reference.
Replace self-signed TLS with valid certificates. See How to configure TLS certificates.
Configure firewall, backups, and monitoring as needed.

Troubleshooting

Services not starting: Check logs with docker-compose logs or bin/production.sh logs.
Database errors: Verify MYSQL_* and database accessibility.
TLS issues: Check certificate paths and permissions.
Port conflicts: Ensure ports 25, 110, 143, 587, 993, 995, 81 are free.

For port details, see Ports reference.