postfixadmin/INSTALL.md

Postfix Admin Installation Guide

Originally by Mischa Peters .

Copyright (c) 2002 - 2005 High5!

Licensed under GPL for more info check LICENSE.TXT

Requirements

• Postfix
• Apache / Lighttpd
• PHP 8.2 or greater (for web server)
• one of the following databases:
  • MariaDB/MySQL
  • PostgreSQL
  • SQLite

READ THIS FIRST!

When this is an upgrade from a previous version of Postfix Admin, please read DOCUMENTS/UPGRADE.TXT also!

If you need to setup Postfix to be able to handle Virtual Domains and Virtual Users check out:

• the PostfixAdmin documentation in the DOCUMENTS/ directory
• our wiki at https://sourceforge.net/p/postfixadmin/wiki/

There are also lots of HOWTOs around the web. Be warned that many of them (even those listed below) may be outdated or incomplete. Please stick to the PostfixAdmin documentation, and use those HOWTOs only if you need some additional information that is missing in the PostfixAdmin DOCUMENTS/ folder.

• https://www.linuxbabe.com/redhat/postfixadmin-create-virtual-mailboxes-centos-mail-server ( Postfix+MySQL+Postfixadmin+Dovecot)

Installation steps

1. Unarchive new Postfix Admin

(if you installed PostfixAdmin as RPM or DEB package, you can skip this step.)

Assuming we are installing Postfixadmin into /srv/postfixadmin, then something like this should work. Please check https://github.com/postfixadmin/postfixadmin/releases to get the latest stable release first (the 4.0.1 version/url below is probably stale)

cd /srv/
wget -O postfixadmin.tgz https://github.com/postfixadmin/postfixadmin/archive/refs/tags/v4.0.1.tar.gz
tar -zxvf postfixadmin.tgz
mv postfixadmin-4.0.1 postfixadmin

Alternatively :

cd /srv
git clone https://github.com/postfixadmin/postfixadmin.git
cd postfixadmin
git checkout postfixadmin-4.0

If you're happy to try out newer functionality and perhaps hit unfixed bugs, you can try the 'master' branch by a git checkout master (or don't run the final git checkout in the above).

Since PostfixAdmin 4.0, you'll need to run the install.sh script to install necessary third party libraries.

/bin/bash install.sh

Which will

• install the 'composer' tool locally (see https://getcomposer.org, creates: composer.phar) and
• download dependent PHP libraries (composer install)
• create a templates_c directory if one does not exist.

2.Setup Web Server

Assuming /var/www/html is where your webserver reads from, either create a symlink:

$ ln -s /srv/postfixadmin/public /var/www/html/postfixadmin

or setup an alias in your webserver config. For Apache, use:

Alias /postfixadmin /srv/postfixadmin/public

3. Setup a Database

With your chosen/preferred database server (i.e. MySQL or PostgreSQL), you need to create a new database. A good name for this could be:

postfix

The mechanics of creating the database vary depending on which server you are using. Most users will find using phpMyAdmin or phpPgAdmin the easiest route.

If you wish to use the command line, you'll need to do something like:

For MySQL:

CREATE DATABASE postfix;
CREATE USER 'postfix'@'localhost' IDENTIFIED BY 'choose_a_password';
GRANT ALL PRIVILEGES ON `postfix` . * TO 'postfix'@'localhost';
FLUSH PRIVILEGES;

For PostgreSQL:

CREATE USER postfix WITH PASSWORD 'whatever';
CREATE DATABASE postfix OWNER postfix ENCODING 'unicode';

For SQLite:

mkdir /srv/postfixadmin/database
touch /srv/postfixadmin/database/postfixadmin.db
sudo chown -R www-data:www-data /srv/postfixadmin/database

(both the directory and the database need to be writeable)

4. Configure PostfixAdmin

The /srv/postfixadmin/config.inc.php file contains all available config options and their default values.

While you can edit config.inc.php directly, doing so will make future updates harder and is not recommended.

Instead, you should create a config.local.php file instead. An example is below.

The most important settings are those for your database server, and the hashing mechanism to be used to store passwords in your database.

Example config.local.php

e.g. /srv/postfixadmin/config.local.php :

<?php
// values in here override what is in config.inc.php.
$CONF['database_type'] = 'mysqli';
$CONF['database_host'] = 'some-server.domain.com';
$CONF['database_user'] = 'postfix';
$CONF['database_password'] = 'postfixadmin';
$CONF['database_name'] = 'postfix';
$CONF['encrypt'] = 'dovecot:SHA512';
$CONF['configured'] = true;

PostfixAdmin does not require write access to any files except the templates_c directory (smarty cache). You can therefore leave the files owned by root (or another user); as long as the web server user (e.g. www-data) can read them, it will be fine.

For templates_c/, allow write access (only) for the web server user (e. g. www-data). The easiest way to do this is

$ mkdir -p /srv/postfixadmin/templates_c $ chown -R www-data /srv/postfixadmin/templates_c

4a. SELinux (CentOS/Fedora etc)

If you're using e.g. CentOS (or another distribution) which enables SELinux, something like the following will be necessary:

semanage fcontext -a -t httpd_sys_content_t "/srv/postfixadmin(/.*)?"
semanage fcontext -a -t httpd_sys_rw_content_t "/srv/postfixadmin/templates_c(/.*)?"
restorecon -R /srv/postfixadmin

(Allow the webserver to read /srv/postfixadmin/* and write to /srv/postfixadmin/templates_c/*)

And if the webserver (PHP) needs to make network connections out to a database server, you'll probably need this:

semanage boolean -m --on httpd_can_network_connect_db

5. Check settings, and create Admin user

Visit http://yourserver.tld/postfixadmin/setup.php in a web browser.

You need to generate a 'setup_password' which is your way of proving you are the 'admin' responsible for this install.

The setup.php page will prompt you to generate a setup_password. Alternatively you can generate one manually using :

php -r "echo password_hash('some password here', PASSWORD_DEFAULT);"

and put the output of that into your config.local.php file - e.g.

$CONF['setup_password'] = '$2y$10$3ybxsh278eAlZKlLf8Zp9e4hmuDaW/TCYd5IZagV7coeAfzBW/GzC';

You need to specify that same password in the setup.php page, and click 'Login with setup_password'

You should then see a list of 'OK' messages.

The setup.php script will attempt to create the database structure (or upgrade it if you're coming from a previous version).

You can then create an Superadmin user (or add another), using the form displayed (you'll need to re-enter the setup password).

6. Use PostfixAdmin

This is all that is needed. Fire up your browser and go to the site that you specified to host Postfix Admin. Login with the Superadmin user you've just created.

7. Integration with Postfix, Dovecot etc.

Now that PostfixAdmin is working, you need to do some configuration in Postfix, Dovecot etc. so that they use the domains, mailboxes and aliases you setup in PostfixAdmin.

The files in the DOCUMENTS/ directory explain which settings you need to do/change.

And finally

If you need help, we'd suggest checking the issue tracker on GitHub: https://github.com/postfixadmin/postfixadmin and/or

IRC - a community of people may be able to help in #postfixadmin on Libera.Chat. See https://web.libera.chat/