Mail Server Series — Part 3

In Part 2, we introduced the overall architecture and the motivation behind building a modern mail server.
From this article onward, we move into the actual implementation.

This third article focuses on two critical components:

• MariaDB (database backend)
• PostfixAdmin (web-based management interface)

Together, they serve as the heart of virtual domain and mailbox management, allowing Postfix and Dovecot to operate smoothly without depending on system accounts.

---

🧩 1. Component Roles

Component	Purpose	Why it’s needed
MariaDB	Stores domains, mailboxes, aliases, passwords	Enables “virtual mailbox” operation for Postfix & Dovecot
PostfixAdmin	Web interface to manage domains, mailboxes, aliases	No need to manually edit SQL or log into servers

This layer allows:

• Adding/deleting domains
• Adding mailboxes
• Managing aliases & forwarders
• Managing alias-domain mappings
• Users to change their own passwords
• Admins to manage all accounts

Everything is managed through a browser—clean and secure.

---

🏗 2. Building the MariaDB Container

Create required directories:

mkdir -p /opt/docker/mail/maildb/data
mkdir -p /opt/docker/mail/maildb/log

Launch MariaDB:

docker run -dit --name maildb \
  --restart=always \
  --network intranet-net \
  -e MARIADB_ROOT_PASSWORD=123456 \
  -e MARIADB_DATABASE=postfix \
  -e MARIADB_USER=postfix \
  -e MARIADB_PASSWORD=postfix1230 \
  -v $PWD/data:/var/lib/mysql \
  -v $PWD/log:/var/log/mysql \
  mariadb:10.11

After MariaDB is up, import the schema:

USE postfix;

SOURCE /opt/docker/mail/maildb/sql/create_mysql.sql;
SOURCE /opt/docker/mail/maildb/sql/addition_mysql.sql;

These SQL files create:

• domain tables
• mailbox tables
• alias tables
• alias_domain tables
• quota tables

---

🖥 3. Deploying PostfixAdmin

Create directories:

mkdir -p /opt/docker/mail/mailsetup/config
mkdir -p /opt/docker/mail/mailsetup/log

Pull the PostfixAdmin image:

docker pull postfixadmin

Start the container (first-time setup):

docker run -dit --name mailsetup \
  --restart=always \
  --network intranet-net \
  -e TZ=Asia/Taipei \
  -e VIRTUAL_HOST=mailsetup.it.demo.tw \
  -p 8082:80 \
  -v $PWD/config:/var/www/html/config \
  postfixadmin

PostfixAdmin requires these steps:

1. Generate a setup_password.
2. Access setup.php to create the admin account.
3. Delete setup.php for security.

---

🛠 4. PostfixAdmin Initial Setup (Secure Workflow)

➤ Step 1: Generate setup_password

Edit config.local.php:

$CONF['setup_password'] = 'paste hash generated by setup.php here';
$CONF['default_aliases'] = array();
$CONF['encrypt'] = 'dovecot:SHA512-CRYPT';

Open your browser:

http://mailsetup.it.demo.tw/setup.php

Generate the password hash → paste it into config.local.php.

➤ Step 2: Create the admin account

Example:

admin@it.demo.tw

Once logged in, you can manage:

• Domains
• Mailboxes
• Aliases
• Alias domains
• Quotas

➤ Step 3: Delete setup.php (MANDATORY)

docker exec -it mailsetup rm -f /var/www/html/setup.php

This prevents configuration hijacking.

---

🔧 5. Integrating PostfixAdmin with MariaDB

PostfixAdmin writes to these tables:

• domain
• mailbox
• alias
• alias_domain

Postfix reads them through MySQL map files such as:

/etc/postfix/sql/virtual_mailboxes.cf
/etc/postfix/sql/virtual_aliases.cf
/etc/postfix/sql/virtual_domains.cf

Example Postfix query:

Mailbox lookup

SELECT 1 FROM mailbox WHERE username='%s' AND active='1';

Alias lookup

SELECT goto FROM alias WHERE address='%s' AND active='1';

This enables Postfix to accept or reject emails correctly.

---

🧪 6. Testing the Integration

✔ Create a domain

it.demo.tw

✔ Create a mailbox

user1@it.demo.tw

Dovecot will map it to:

/var/mail/it.demo.tw/user1/

✔ Test IMAP login

Roundcube → Dovecot → MariaDB → PostfixAdmin

✔ Send and receive emails

Verifies:

• Alias resolution
• Virtual transports
• Dovecot LMTP delivery
• Anti-spam / anti-virus filters (Amavis, SA, ClamAV)

---

🧾 7. FAQ / Troubleshooting

Q1. IMAP login failed?

Check:

• mailbox.active = 1
• Password is SHA512-CRYPT format
• Domain name mapping is correct

Q2. Domain deleted but maildir still exists?

PostfixAdmin does not remove maildirs.

Manually clean them:

rm -rf /var/mail/it.demo.tw/user1/

Q3. Do users from different domains share accounts?

No — each domain has its own namespace.

---

🔚 Conclusion: The Foundation Layer of Virtual Mail Hosting

In this article, we have completed the essential account management layer:

• MariaDB database backend
• PostfixAdmin management interface
• Virtual domain & mailbox model
• Alias management
• Password encryption (Dovecot SHA512-CRYPT)
• Secure setup workflow

This forms the foundation for Postfix, Dovecot, and the entire email system.