postfixadmin/DOCUMENTS/UPGRADE.txt

#
# Postfix Admin
# by Mischa Peters <mischa at high5 dot net>
# Copyright (c) 2002 - 2005 High5!
# Licensed under GPL for more info check GPL-LICENSE.TXT
#

REQUIRED!!
----------
- You are using Postfix 2.0 or higher.
- You are using Apache 1.3.27 / Lighttpd 1.3.15 or higher.
- You are using PHP 5.1.2 or higher.
- You are using MySQL 3.23 or higher OR PostgreSQL v7.4+


READ THIS FIRST!
----------------

This document describes upgrading from an older PostfixAdmin version
(>= v1.5x)

It's recommend that you install Postfix Admin in a new folder and not
on-top of the old install!! (At the very least, make sure you have backups of 
the database and relevant filesystem!)

When upgrading Postfix Admin, make sure you backup your database before
running upgrade.php.


1. Backup the Database
----------------------
When you install from a previous version make sure you backup your database
first. There are a lot of changes in the database structure since Postfix Admin
1.5.4.

  $ mysqldump -u root -p postfixdb > /tmp/postfixadmin-backup.sql
or
  $ pg_dump -ad -u postfix postfixdb > /tmp/postfixadmin-backup.sql

(Replace postfixdb with your Postfixadmin database's name)

2. Unarchive new Postfix Admin
------------------------------
Make sure that you are in your WWW directory and then unarchive the
Postfix Admin archive (whatever the filename is):

  $ tar -zxvf postfixadmin-X.X.tgz


3. Change permissions
----------------------
Since the database password is stored in the config.inc.php it's a good idea
to have change the permissions for Postfix Admin.

  $ cd /usr/local/www/postfixadmin
  $ find -type f -print0 | xargs -0 chmod 640
  $ find -type f -print0 | xargs -0 chown root:www-data

(the last command assumes your Apache is running with group "www-data")

Since version 3.0 we use smarty templates. That means the templates_c directory
needs to be writeable for your webserver.

  $ cd /usr/local/www/postfixadmin
  $ mkdir templates_c && chmod 750 templates_c && chown -R www-data templates_c

(if your Apache runs as user "www-data")

If you have SELinux enabled, also run (adust the path to match your setup)

  $ sudo semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/utils/pfadmin/public/templates_c(/.*)?"
  $ sudo restorecon -Rv /var/www/utils/pfadmin/


4. Configure
------------

Check the config.inc.php file. There you can specify settings that are
relevant to your setup.

Comparing config.inc.php with your previous using "diff" might save you some
time.

You can use a config.local.php file to contain your local settings. 
These will override any defined in config.inc.php - and save some time when upgrading to a new version of PostfixAdmin ;-)

5. Run setup.php
----------------------------------------

Access setup.php through a web browser.

It will attempt to upgrade your database, and also allow you to create a superadmin user.
(In case the database upgrade fails, you can run setup.php?debug=1 to see the last executed query.)

From version 2.3, you need to specify a setup_password in config.inc.php - 
setup.php should guide you through this process. If you do not have a setup_password, type one
into the form, and setup.php will echo out the hashed value (which needs to go into config.inc.php).
The setup_password removes the requirement for you to delete setup.php, and also closes a security hole.

Since version 2.2 of Postfixadmin, setup.php can perform the needed database 
updates automatically .

If you update from 2.1 or older, also create a superadmin account using setup.php.

Note that admin/ has been merged into the main directory. Login with the
superadmin account to setup domains and domain admins.

6. Upgrade your postfix config
------------------------------

Since version 2.3, PostfixAdmin supports alias domains ($CONF['alias_domain']).
If you want to use them, you have to add some queries to your postfix config -
see POSTFIX_CONF for details.


7. Done
-------
This is all that is needed. Fire up your browser and go to the site that you
specified to host Postfix Admin.