Install guide

Installing

Deploy MxCentral from your workstation, keep server secrets on the mail host, then wire MxCentral into the existing iRedMail nginx, sudo, ACL, cron, and service paths.

Start install Back to overview

Deploy targetSet DEPLOY_HOST and DEPLOY_PATH in ignored Makefile.local.

DependenciesMake sure vendor/ exists before deploy, or run Composer on the server after rsync.

Server configCreate .env on the iRedMail server and keep credentials out of deployment.

Host wiringInstall sudoers, ACLs, nginx mount, Laravel cache clear, cron, and checks.

1. Configure the private deploy target.

On your workstation, create an ignored Makefile.local. This keeps the production host and destination path out of the repository.

paul@mxcentral.net:~/mxcentral-for-iRedmail$ cat > Makefile.local <<'EOF'
DEPLOY_HOST := root@your-mail-server
DEPLOY_PATH := /opt/www/mxcentral-for-iRedmail
EOF

2. Make Composer dependencies available.

The current deploy target does not run Composer. Install dependencies locally before deployment, or deploy first and run Composer in /opt/www/mxcentral-for-iRedmail on the server.

paul@mxcentral.net:~/mxcentral-for-iRedmail$ cd mxcentral-for-iRedmail
paul@mxcentral.net:~/mxcentral-for-iRedmail/mxcentral-for-iRedmail$ composer install --no-dev --optimize-autoloader
paul@mxcentral.net:~/mxcentral-for-iRedmail/mxcentral-for-iRedmail$ cd ..
paul@mxcentral.net:~/mxcentral-for-iRedmail$ make deploy

3. Create the server environment file.

On the iRedMail server, create .env manually because deploy deliberately does not overwrite it. Generate the Laravel app key as www-data.

Set APP_URL=https://your-mail-host.example/mxcentral.
Set IREDMAIL_DB_HOST, IREDMAIL_DB_USERNAME, and IREDMAIL_DB_PASSWORD.
Confirm database names for vmail, iredadmin, amavisd, iredapd, and fail2ban.
Set command paths and DKIM, Postfix, iRedAPD, SOGo, Fail2ban, and mail notification settings from INSTALL.md.

paul@mxcentral.net:/opt/www/mxcentral-for-iRedmail$ cp .env.example .env
paul@mxcentral.net:/opt/www/mxcentral-for-iRedmail$ sudo -u www-data php artisan key:generate

4. Install the sudoers include.

Validate the provided sudoers file before installing it. Use a dotless filename under /etc/sudoers.d.

paul@mxcentral.net:/opt/www/mxcentral-for-iRedmail$ visudo -cf /opt/www/mxcentral-for-iRedmail/docs/sudoers.conf
paul@mxcentral.net:/opt/www/mxcentral-for-iRedmail$ install -o root -g root -m 0440 /opt/www/mxcentral-for-iRedmail/docs/sudoers.conf /etc/sudoers.d/mxcentral-for-iRedmail

5. Run the one-time ACL setup.

Follow the ACL commands in INSTALL.md so www-data can manage only the files MxCentral is expected to manage.

/etc/amavis/conf.d/50-user
/var/lib/dkim
/opt/iredapd/settings.py
/etc/postfix/main.cf
/etc/postfix/sender_access.pcre
/etc/postfix/discard_recipients
The SOGo root template path

Keep the permission surface narrow.

Do not make the application user own the whole mail server. The install flow gives it the specific write access needed for DKIM, policy, Postfix, iRedAPD, SOGo, and related checks.

6. Mount the app in nginx.

Configure nginx to mount /mxcentral to the Laravel public directory. Include the provided template before broad PHP catchall rules in the active iRedMail server block, then test and reload nginx.

paul@mxcentral.net:/opt/www/mxcentral-for-iRedmail$ ls docs/nginx/mxcentral.tmpl
docs/nginx/mxcentral.tmpl

paul@mxcentral.net:/opt/www/mxcentral-for-iRedmail$ nginx -t
paul@mxcentral.net:/opt/www/mxcentral-for-iRedmail$ systemctl reload nginx

7. Clear caches and add cron.

Clear Laravel caches after the environment is in place, then add the scheduler entry manually.

paul@mxcentral.net:/opt/www/mxcentral-for-iRedmail$ sudo -u www-data php artisan optimize:clear

* * * * * /usr/bin/php /opt/www/mxcentral-for-iRedmail/bin/cron.php >/dev/null 2>&1

8. Run post-install checks.

Confirm Laravel can read routes and run the quarantine notification command. Also verify write access for iRedAPD, Amavisd, and Postfix paths as shown at the end of INSTALL.md.

paul@mxcentral.net:/opt/www/mxcentral-for-iRedmail$ sudo -u www-data php artisan route:list >/dev/null
paul@mxcentral.net:/opt/www/mxcentral-for-iRedmail$ sudo -u www-data php artisan quarantine:notify-recipients --dry-run

Main thing to watch

The deploy path assumes the application directory already contains vendor/, or that Composer will be run on the server after deployment.