PostfixAdmin for Debian
=======================
After installing the package, you should do a few things to finish the setup.

You should go to http://localhost/postfixadmin/setup.php and
follow the instructions.

If you cannot get to the URL above, double check the followings:
 - do you have a working web server setup that can process php?
 - do you have the correct database credentials in /etc/postfixadmin ?

You can look at /etc/postfixadmin/config.inc.php to see the default settings,
then apply your custom configs in /etc/postfixadmin/config.local.php, for
example, it is recommended to add this to /etc/postfixadmin/config.local.php:

<?php
$CONF['encrypt'] = 'dovecot:ARGON2ID';

Remember that Debian does things differently from upstream. This means
that "INSTALL.TXT" in the source tarball has a lot of places should not
be applied to Debian. For example, the webroot is /usr/share/postfixadmin/public,
which is owned by root:root, so you should not need to touch that directory.


Postfix, Dovecot, Postgresql
============================
For users using postfix, dovecot, postgresql with postfixadmin, refer
to /usr/share/doc/postfixadmin/DOCUMENTS/Postfix-Dovecot-Postgresql-Example.md.gz
for an example configuration.


Postfix, Dovecot, Mariadb
=========================
For users using postfix, dovecot, mariadb with postfixadmin, I paste the
configurations of my mail server here (with a few changes) for your reference:

/etc/postfix/main.cf:
--------------------
# you would need to add these lines
relay_domains = proxy:mysql:/etc/postfix/sql/mysql_relay_domains.cf
transport_maps = proxy:mysql:/etc/postfix/sql/mysql_transport_maps.cf
virtual_transport = virtual
local_transport = virtual
local_recipient_maps = $virtual_mailbox_maps
virtual_mailbox_base = /var/mail/vmail
mailbox_size_limit = 1073741824
virtual_mailbox_limit = $mailbox_size_limit
virtual_minimum_uid = 8
virtual_uid_maps = static:8
virtual_gid_maps = static:8
virtual_mailbox_domains = proxy:mysql:/etc/postfix/sql/mysql_virtual_domains_maps.cf
virtual_alias_maps =
   proxy:mysql:/etc/postfix/sql/mysql_virtual_alias_maps.cf,
   proxy:mysql:/etc/postfix/sql/mysql_virtual_alias_domain_maps.cf,
   proxy:mysql:/etc/postfix/sql/mysql_virtual_alias_domain_catchall_maps.cf
virtual_mailbox_maps =
   proxy:mysql:/etc/postfix/sql/mysql_virtual_mailbox_maps.cf,
   proxy:mysql:/etc/postfix/sql/mysql_virtual_alias_domain_mailbox_maps.cf
smtpd_sender_login_maps = proxy:mysql:/etc/postfix/sql/mysql_virtual_sender_maps.cf
smtpd_sasl_security_options = noanonymous, noplaintext
smtpd_sasl_tls_security_options = noanonymous
smtpd_sasl_authenticated_header = yes
smtpd_sasl_type = dovecot
smtpd_sasl_path = private/auth
smtpd_sasl_auth_enable = yes

/etc/postfix/sql/mysql_relay_domains.cf:
----------------------------------------
user = postfixadmin
password =
hosts =
dbname = postfixadmin
query = SELECT domain FROM domain WHERE domain='%s' AND active = '1' AND (transport LIKE 'smtp%%' OR transport LIKE 'relay%%')

/etc/postfix/sql/mysql_transport_maps.cf:
-----------------------------------------
user = postfixadmin
password =
hosts =
dbname = postfixadmin
# Enforce virtual transport (catches internal virtual domains and avoid mails being lost in other transport maps)
query = SELECT REPLACE(transport, 'virtual', ':') AS transport FROM domain WHERE domain='%s' AND active = '1'

/etc/postfix/sql/mysql_virtual_alias_domain_catchall_maps.cf:
-------------------------------------------------------------
user = postfixadmin
password =
hosts =
dbname = postfixadmin
query  = SELECT goto FROM alias,alias_domain WHERE alias_domain.alias_domain = '%d' and alias.address = CONCAT('@', alias_domain.target_domain) AND alias.active='1' AND alias_domain.active='1'

/etc/postfix/sql/mysql_virtual_alias_domain_mailbox_maps.cf:
------------------------------------------------------------
user = postfixadmin
password =
hosts =
dbname = postfixadmin
query = SELECT maildir FROM mailbox,alias_domain WHERE alias_domain.alias_domain = '%d' and mailbox.username = CONCAT('%u', '@', alias_domain.target_domain) AND mailbox.active='1' AND alias_domain.active='1'

/etc/postfix/sql/mysql_virtual_alias_domain_maps.cf:
----------------------------------------------------
user = postfixadmin
password =
hosts =
dbname = postfixadmin
query = SELECT goto FROM alias,alias_domain WHERE alias_domain.alias_domain = '%d' and alias.address = CONCAT('%u', '@', alias_domain.target_domain) AND alias.active='1' AND alias_domain.active='1'

/etc/postfix/sql/mysql_virtual_alias_maps.cf:
---------------------------------------------
user = postfixadmin
password =
hosts =
dbname = postfixadmin
query = SELECT goto FROM alias WHERE address='%s' AND active = '1'

/etc/postfix/sql/mysql_virtual_domains_maps.cf:
-----------------------------------------------
user = postfixadmin
password =
hosts =
dbname = postfixadmin
query = SELECT domain FROM domain WHERE domain='%s' AND active = '1' AND NOT (transport LIKE 'smtp%%' OR transport LIKE 'relay%%')
# add "AND backupmx = '0'" when relaying for backup MX

/etc/postfix/sql/mysql_virtual_mailbox_limit_maps.cf:
-----------------------------------------------------
user = postfixadmin
password =
hosts =
dbname = postfixadmin
query = SELECT quota FROM mailbox WHERE username='%s' AND active = '1'

/etc/postfix/sql/mysql_virtual_mailbox_maps.cf:
-----------------------------------------------
user = postfixadmin
password =
hosts =
dbname = postfixadmin
query = SELECT maildir FROM mailbox WHERE username='%s' AND active = '1'

/etc/postfix/sql/mysql_virtual_sender_maps.cf:
----------------------------------------------
user = postfixadmin
password =
hosts =
dbname = postfixadmin
query = SELECT username FROM mailbox WHERE username='%s' AND active = true

Additionally, you should check out postfix's docs and manpages. You would
want to get a Let's Encrypt certificate, for postfixadmin, postfix stmpd,
and also dovecot.


Next, dovecot:

/etc/dovecot/dovecot-sql.conf.ext:
----------------------------------
# replace or add these lines
driver = mysql
connect = host=... dbname=postfixadmin ...
# ARGON2ID is recommended
default_pass_scheme = ARGON2ID
password_query = SELECT username AS user,password FROM mailbox WHERE username = '%u' AND active='1'
user_query = SELECT CONCAT('/var/mail/vmail/', maildir) AS home, 500 AS uid, 500 AS gid, CONCAT('*:bytes=', quota) AS quota_rule FROM mailbox WHERE username = '%u' AND active='1'
iterate_query = SELECT username as user FROM mailbox WHERE active = '1'

/etc/dovecot/conf.d/10-auth.conf:
---------------------------------
# uncomment this line
!include auth-sql.conf.ext



Recommended and Suggested Packages
==================================
 - Postfix
 - MySQL or PostgreSQL
 - Courier or Dovecot
 

Where to get help
=================
The first stop would be the Postfixadmin Website or IRC channel.

See :
 - https://github.com/postfixadmin/postfixadmin
 - #postfixadmin on libera.chat

 -- Luke Yasuda <jing@jing.rocks>  Fri, 07 Nov 2025 05:34:55 +0900
