Install PostfixAdmin

This guide explains how to install PostfixAdmin 4.0.5 on Ubuntu with Nginx, PHP 8.5, and MariaDB.

Install Required Packages

sudo apt update
sudo apt install -y wget unzip composer git
cd /tmp
wget https://github.com/postfixadmin/postfixadmin/archive/refs/tags/v4.0.5.tar.gz
tar -xzf v4.0.5.tar.gz
sudo mv /tmp/postfixadmin-4.0.5 /var/www/postfixadmin
cd /var/www/postfixadmin
composer install --no-dev
sudo rm -f /var/www/html/postfixadmin
sudo ln -s /var/www/postfixadmin/public /var/www/html/postfixadmin
sudo chown -R www-data:www-data /var/www/postfixadmin
sudo find /var/www/postfixadmin -type d -exec chmod 755 {} \;
sudo find /var/www/postfixadmin -type f -exec chmod 644 {} \;
sudo nginx -t
sudo systemctl reload nginx

dbconfig-common

During the installation you will be asked:

Configure database for postfixadmin with dbconfig-common?

Select No. The database will be configured manually.

Create the Database User

Log in to MariaDB:

sudo mysql

Create a dedicated database user for PostfixAdmin:

CREATE USER 'postfixadmin'@'localhost'
IDENTIFIED BY 'YOUR_STRONG_PASSWORD';

GRANT ALL PRIVILEGES ON mailserver.*
TO 'postfixadmin'@'localhost';

FLUSH PRIVILEGES;

Configure Nginx

Edit the default Nginx site:

sudo nano /etc/nginx/sites-available/default

Uncomment the PHP block and use your PHP 8.5 socket:

location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php8.5-fpm.sock;
}

Make sure the index directive contains index.php. For example:

index index.php index.html index.htm;

Test the configuration and reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

Configure PostfixAdmin

Create the configuration file:

sudo nano /var/www/postfixadmin/config.local.php

Paste the following configuration:

<?php

$CONF['configured'] = true;

$CONF['database_type'] = 'mysqli';
$CONF['database_host'] = 'localhost';
$CONF['database_user'] = 'postfixadmin';
$CONF['database_password'] = 'YOUR_POSTFIXADMIN_PASSWORD';
$CONF['database_name'] = 'mailserver';

$CONF['encrypt'] = 'dovecot:ARGON2ID';

$CONF['domain_path'] = 'YES';
$CONF['domain_in_mailbox'] = 'NO';

Open the PostfixAdmin setup page (http://mail.myDomain.com/postfixadmin/setup.php) and enter your initial setup password. After submitting it, PostfixAdmin will generate a hashed setup password and display a configuration line similar to this:

$CONF['setup_password'] = 'YOUR_GENERATED_SETUP_PASSWORD';

Copy the generated line and add it to:

sudo nano /var/www/postfixadmin/config.local.php

Create the Web Symlink

Create the symbolic link for the PostfixAdmin web interface:

sudo ln -s /usr/share/postfixadmin/public /var/www/html/postfixadmin

Note: If you already created a symbolic link to /var/www/postfixadmin/public during the installation, you do not need to execute this command again.

Verify the Configuration

If it is not already present, ensure that index.php is included in the Nginx configuration:

sudo nano /etc/nginx/sites-available/default

Finally, verify that the PostfixAdmin configuration file exists and contains the correct database credentials:

sudo nano /var/www/postfixadmin/config.local.php

Now first start setup: http://mail.myDomain.com/postfixadmin/setup.php

Here I received the error:

⛔Database connection string : mysql:host=localhost;dbname=mailserver
⛔Problem connecting to database, check database configuration ($CONF['database_*'] entries in config.local.php)
⛔SQLSTATE[HY000] [1045] Access denied for user 'postfixadmin'@'localhost' (using password: YES)

So, I executed:

grep -E "database_(host|user|password|name)" /var/www/postfixadmin/config.local.php

And saw that password was wrong, thats why I change it again:

sudo nano /var/www/postfixadmin/config.local.php

The I had the error:

⛔Password Hashing - attempted to use configured encrypt backend (dovecot:ARGON2ID) triggered an error: /usr/bin/doveadm pw failed, see error log for details
⛔You will have problems logging into PostfixAdmin.
⛔Check out our Dovecot documentation at

So, I executed:

sudo -u www-data /usr/bin/doveadm pw -s ARGON2ID

Since I received permission denied I executed:

sudo usermod -aG dovecot www-data
sudo usermod -aG dovecot www-data
sudo systemctl restart php8.5-fpm
sudo systemctl restart nginx

And again, I executed:

sudo -u www-data /usr/bin/doveadm pw -s ARGON2ID

This time without permission denied

You can now log in to PostfixAdmin as an administrator at http://mail.myDomain.com/postfixadmin/login.php, or as a mailbox user at http://mail.myDomain.com/postfixadmin/users/login.php. Replace myDomain.com with your own domain name.

If you receive an error then run these commands immediately after opening

sudo tail -50 /var/log/nginx/error.log
sudo journalctl -u php8.5-fpm -n 50 --no-pager

Reset the Administrator Password

Check whether the mailserver database exists:

sudo mariadb -e "SHOW DATABASES LIKE 'mailserver';"

Check whether a user has access to mailserver:

sudo mariadb -e "SHOW GRANTS FOR 'postfixadmin'@'localhost';"

If you forgot the PostfixAdmin administrator password, first list the existing administrator accounts:

sudo mariadb mailserver -e "SELECT username FROM admin;"

If the previous command returns an administrator account such as adminmail@myDomain.com, reset its password with:

cd /var/www/postfixadmin

php scripts/postfixadmin-cli.php admin update adminmail@myDomain.com \
  --password "MyNewAdminPassword123!" \
  --password2 "MyNewAdminPassword123!"

Reset a Mailbox Password

If you forgot a mailbox password, first list the existing mailbox accounts:

sudo mariadb mailserver -e "SELECT username FROM mailbox;"

If the previous command returns a mailbox account such as myUser@myDomain.com, reset its password with:

cd /var/www/postfixadmin

php scripts/postfixadmin-cli.php mailbox update myUser@myDomain.com \
  --password "MyNewMailboxPassword123!" \
  --password2 "MyNewMailboxPassword123!"