Skip to content

Software Installation Guide

General Information

Before deploying the software, review the configuration/settings file for your instance. Ensure that the settings.php file is correctly configured. While this software has been successfully used in many production environments, there are no absolute guarantees.

This software has been tested on Ubuntu and Debian systems, though it may work on other systems that have not been tested. If using a system other than Debian or Ubuntu, you might need to adjust deeper settings within the settings.php file. This software is optimized for Debian/Ubuntu with Apache and PHP 8. Below are the requirements and installation steps to follow:

Requirements

To ensure smooth operation of the web software alongside Dovecot for managing mail SSL certificates, the following requirements must be met:

Server Dependencies

  • Root permissions for cronjobs on the system.
  • Dovecot: Ensure that Dovecot is installed and properly configured on your server.
  • OpenSSL: Required for handling SSL/TLS certificates.
  • Postfix (or an equivalent MTA): For handling outgoing mail. Postfix 3.4 or newer is needed for the optional per-domain SMTP certificates.
  • Web Server: Apache, Nginx, or any compatible server for hosting the web software.
  • MySQL database: Connection and user credentials (configured in settings.php).

Apache Requirements

  • Apache2 web server with PHP 7/8 support.
  • Apache2 modules: rewrite.

PHP Requirements

  • PHP Version: 8.X
  • PHP modules: mysqli, curl, intl, mbstring, gd.
  • PHP CLI: The PHP command line interpreter (php) is needed to execute the cronjobs.

System Requirements

  • Operating System: Linux-based OS (e.g., Ubuntu, CentOS, Debian) is recommended.
  • RAM: Minimum of 1GB.
  • Disk Space: At least 10GB of free space for logs, emails, and software.

Installation Procedure

  1. Upload Files: Upload the files from the "source" directory of this repository to your web space.
  2. Configure Settings: Check the settings.sample.php file and make the necessary changes. Set your MySQL login credentials in the settings.php file.
  3. Rename Configuration File: Rename settings.sample.php to settings.php.
  4. Automatic SQL Tables: The software will automatically create any required SQL tables when the website is first opened. An initial user will be created, and login credentials will be provided at the end of this guide.
  5. Setup Cronjob: Configure the cronjob as described below. Without it, Dovecot configuration will not be written.
  6. Edit Dovecot Configuration: It is crucial to modify the dovecot.conf file as described in the documentation below.
  7. Edit Postfix Configuration (Optional): For per-domain SMTP certificates, execute the postfix_smtp.php cronjob once and then add the map to the Postfix main.cf file as described in the documentation below.

Initial Setup

After uploading the project files to the server (outside of the source directory), modify the settings.sample.php file as needed and rename it to settings.php. This step is mandatory to ensure the software functions correctly, as valid MySQL user data is required.

Configuration Settings

Below is a list of settings you can configure in the settings.php file:

Constant Description
_TITLE_ Set the website title, which will be shown in your browser tab.
_IMPRESSUM_ Link to your impressum page, accessible from the footer.
_SQL_HOST_ SQL Database Host.
_SQL_USER_ SQL Database User.
_SQL_PASS_ SQL Database Password.
_SQL_DB_ SQL Database name.
_IP_BLACKLIST_DAILY_OP_LIMIT_ IP blacklist limit for blocking IPs (default is 1000). Reset daily if the cronjob daily.php is executed.
_CSRF_VALID_LIMIT_TIME_ Validity period of a CSRF key for form validation (default is 1000 seconds).
_MYSQL_LOGGING_ Set to "true" to enable MySQL logging and the debug area in the web interface. Set to "false" to disable.
_COOKIES_ Cookie prefix. No need to change unless you are familiar with the implications.
_CRON_DOVECOT_FILE_ Path to the Dovecot configuration file for SSL certificate/domain settings. Include this in dovecot.conf.
_CRON_ISP_FOLDER_SEARCH_ Path for fetching subfolder names from ISPConfig (only needed if using ISPConfig).
_CRON_POSTFIX_FILE_ Optional and not part of settings.sample.php. Path of the Postfix SNI map written by the postfix_smtp.php cronjob (default is /etc/postfix/dci.sni.map). To change it, add define("_CRON_POSTFIX_FILE_", "/your/path/dci.sni.map"); to settings.php.

Cronjob Setup

To ensure the software operates correctly, configure the following cronjobs. The cronjobs need root permissions and have to be executed with the PHP command line interpreter, for example php _webroot_/_cronjob/sync.php. They do not run if they are requested through the web server.

Mandatory Cronjobs

Command Interval Description
_webroot_/_cronjob/daily.php Daily Resets blacklisted IPs (optional but recommended).
_webroot_/_cronjob/sync.php X Executes all domain and Dovecot related operations. Recommended interval: hourly. This is mandatory.

Optional ISP Config Domain Fetch Cronjob

Command Interval Description
_webroot_/_cronjob/ispconfig_fetch.php X Fetches SSL certificates and domains from ISPConfig webroot folders. Only needed if using ISPConfig.

Optional Postfix SMTP Certificates Cronjob

Command Interval Description
_webroot_/_cronjob/postfix_smtp.php X Writes all enabled domains into the Postfix SNI map and reloads Postfix, so Postfix presents the matching certificate for each domain. Recommended interval: same as sync.php (hourly). Only needed for per-domain SMTP certificates, see "Edit Postfix Configuration" below.

Example Crontab

Example for the crontab of the root user (crontab -e). Replace _webroot_ with the path of your installation and remove the optional lines you do not need:

0 * * * * php _webroot_/_cronjob/sync.php > /dev/null 2>&1
0 3 * * * php _webroot_/_cronjob/daily.php > /dev/null 2>&1
# Optional: only if using ISPConfig
55 * * * * php _webroot_/_cronjob/ispconfig_fetch.php > /dev/null 2>&1
# Optional: only for per-domain SMTP certificates with Postfix
5 * * * * php _webroot_/_cronjob/postfix_smtp.php > /dev/null 2>&1

Edit Dovecot Configuration

Important: Modify the dovecot.conf file to make the script work. Add the following line to the end of the file:

!include_try dci.certs.conf

Edit Postfix Configuration (Optional)

This step is only needed if Postfix should present the per-domain certificates for SMTP as well, so mail clients can use their own domain as SMTP server name, exactly like for IMAP/POP3 with Dovecot. Postfix 3.4 or newer is required, you can check your version with postconf -h mail_version.

Important: Execute the postfix_smtp.php cronjob once as root before changing the Postfix configuration. Postfix SMTP fails as long as the configured map has not been created.

php _webroot_/_cronjob/postfix_smtp.php

Afterwards, add the following line to the end of the Postfix main.cf file (usually /etc/postfix/main.cf) and reload Postfix:

tls_server_sni_maps = hash:/etc/postfix/dci.sni.map

postfix reload
  • Map Type: As long as the map is not configured in Postfix, the cronjob uses the default database type of your Postfix (postconf -h default_database_type), which is hash on most systems. The exact line to add is shown in the output of the cronjob and in the "Log" section of the web interface. If another type is shown there, for example lmdb, use that one instead of hash.
  • Map Location: If you changed _CRON_POSTFIX_FILE_ in settings.php, use that path instead of /etc/postfix/dci.sni.map.
  • Automatic Reload: As soon as Postfix uses the map, the cronjob reloads Postfix automatically after each run.
  • Certificate Renewal: The certificates are copied into the compiled map. Renewed certificates are used after the next run of the cronjob, so execute it in the same interval as sync.php.
  • Permissions: The map files contain the private keys and are only readable by root.
  • Default Certificate: Clients that send no server name, or a name that is not in the map, get the default certificate configured in main.cf (smtpd_tls_chain_files or smtpd_tls_cert_file and smtpd_tls_key_file).
  • Single Services: To use the per-domain certificates only for a single service (for example submission on port 587), add -o tls_server_sni_maps=hash:/etc/postfix/dci.sni.map to that service in master.cf instead of changing main.cf. The cronjob detects the map there as well.
  • Revert: Remove the line from main.cf (or master.cf), execute postfix reload and remove the cronjob. Afterwards, the files /etc/postfix/dci.sni.map* can be deleted.

Check the Certificates (Optional)

After the cronjobs have been executed, you can check which certificate is presented for a domain. Replace mail.example.com with one of your domains. The first command checks Dovecot (IMAPS), the second one Postfix (submission):

openssl s_client -connect mail.example.com:993 -servername mail.example.com < /dev/null 2>/dev/null | openssl x509 -noout -subject -dates
openssl s_client -connect mail.example.com:587 -starttls smtp -servername mail.example.com < /dev/null 2>/dev/null | openssl x509 -noout -subject -dates

Initial Login

After successfully deploying the software, log in with the following credentials:

  • Username: admin
  • Password: changeme

Important: Change the initial password after the first successful login.