0) dependencies-server:
    webserver with PHP5
    MySQL-Server
    Zend Framework 1.7.x
    PDO extension for PHP5
    (and of course a mailserver setup compatible with http://struction.de/projects/HOWTO_VirtualMail_Exim-MySQL-Spamassassin-ClamAV-Dovecot/)
   dependencies-client:
    xhtml browser, css
    javascript is optional and adds some clientside features
    cookies for session management
1) unpack

2) if your webserver does not support Apache .htaccess you need to figure out the corresponding settings for your webserver
    (URL rewrite to index.php of all non-static URLs)
    you have to create rename .htaccess.default to .htaccess (and modify it to your needs)
    you should enable ssl for smad to avoid eavesdroping

3) create config/config.xml
   use provided example. it contains sane defaults for the features
   and it should be obvious what to change
   (at least:  webhost, host, username, password and dbname)

4) configure index.php
    it is useful to look at the source of the application.
    its designed to be extendable and customized. read more in the
    embedded documentation

5) setup database
    create MySQL user for smad according your config from step 3:
      GRANT USAGE ON *.* TO 'smad'@'localhost' IDENTIFIED BY 'SMADPASSWORD' WITH MAX_QUERIES_PER_HOUR 0 MAX_CONNECTIONS_PER_HOUR 0 MAX_UPDATES_PER_HOUR 0 MAX_USER_CONNECTIONS 0;
      GRANT SELECT, INSERT, UPDATE, DELETE ON `system`.* TO 'smad'@'localhost';

    add table management_permission to your database:
      CREATE TABLE `management_permission` (
        `id` int(11) NOT NULL auto_increment,
        `username` varchar(128) NOT NULL COMMENT 'local-part of email-address',
        `domain` varchar(64) NOT NULL COMMENT 'domain-part of email-address',
        `role` enum('admin','domainadmin', 'user') NOT NULL COMMENT 'administrative role',
        `data` varchar(255) NOT NULL COMMENT 'domain, this domainadmin is allowed to edit',
        `last_modified` timestamp NOT NULL default CURRENT_TIMESTAMP on update CURRENT_TIMESTAMP,
        PRIMARY KEY  (`id`),
        KEY `username` (`username`),
        KEY `domain` (`domain`)
      ) ENGINE=MyISAM  DEFAULT CHARSET=utf8 COMMENT='user management permission (frontend use only)';
    (this stores the permissions/role a user in SMAD. the user is authenticated against the user-table of the virtual mail system.)

    elevate an existing virtual mail system user to admin:
    (see http://struction.de/projects/HOWTO_VirtualMail_Exim-MySQL-Spamassassin-ClamAV-Dovecot/index?set_lang=en#AddUser for details creating a user manually to solve the chicken-or-the-egg causality dilemma)
    if user@example.com is a user in your virtual mail system, make him an admin with:
      INSERT INTO `management_permission` (`username`, `domain`, `role`) VALUES ('user', 'example.com', 'admin');

now you should be able to log in and manage your virtual mail system.

* when it does not work:
 check config file
 check db-config (GRANT)
 a BLANK page points to db-misconfiguration

you can turn on debugging mode to get error messages by setting the environment variable ZEND_DEBUG = development. e.g. in your .htaccess:
    SetEnv ZEND_DEBUG = development

if you are upgrading, please also read UPGRADE!