# How to install Mautic 7 with Composer, Apache, MariaDB and HTTPS

> Install Mautic 7 the Composer way on Ubuntu 24.04 or Debian 12 with Apache, PHP, MariaDB and Caddy HTTPS, then add cron jobs, SMTP email, backups and updates.

Difficulty: Advanced\
Tested on: Ubuntu 24.04 LTS, Debian 12

Mautic is an open-source marketing automation platform: it tracks contacts, builds segments, runs multi-step campaigns and sends emails, with forms and landing pages to capture leads. This guide installs **Mautic 7** from the official Composer project, which Mautic's documentation names as the default way to install, update and manage Mautic since Mautic 6. Apache with PHP and MariaDB runs Mautic on a local port, Caddy in front provides automatic HTTPS, the installer runs from the shell, cron runs the background jobs, and a transactional email service delivers your messages. Backups, updates and troubleshooting complete the setup.

> **Note**
>
> Official Docker images for Mautic exist as well. Their README warns not to use the example setups in production without reviewing, understanding and configuring them, so this guide follows the documented Composer method.

## Prerequisites

- A server running **Ubuntu 24.04 LTS** (PHP 8.3) or **Debian 12** (PHP 8.2). Mautic 7 supports PHP 8.2 to 8.5, but its Composer files require the PHP `imap` extension; Ubuntu 26.04 and Debian 13 ship PHP 8.4 without a `php-imap` package, so they are not covered here.
- A non-root user with `sudo` rights and SSH key login: [Secure a new Linux server](/guides/secure-a-new-linux-server) and [Set up SSH keys](/guides/ssh-keys).
- A domain name such as `mautic.example.com` with an A record (and optionally an AAAA record) pointing at the server.
- Caddy from [Caddy reverse proxy](/guides/caddy-reverse-proxy), needed in Step 7.
- An account with a transactional email provider or SMTP relay, with SPF and DKIM set up for your sending domain as the provider describes.

Mautic does not publish CPU or memory minimums; its requirements page says not to install it on shared hosting and to use a VPS or dedicated server. It does set software minimums: PHP 8.2 or newer for Mautic 7, MySQL 5.7 or MariaDB 10.2 or newer with InnoDB, and a PHP `max_execution_time` of at least 240 seconds. The column on the right is a conservative starting point, not an official figure:

| Resource | Minimum (official) | Suggested starting point |
|---|---|---|
| CPU | Not published | 2 vCPU |
| RAM | Not published | 4 GB |
| Disk | Not published | 40 GB, more for large contact databases |

## Step 1 — Install Apache, PHP, MariaDB and Composer

Install the web server, PHP with every extension on Mautic's list, the database server and Composer from your distribution:

```bash
sudo apt update
sudo apt install apache2 libapache2-mod-php php-cli php-mysql php-xml php-imap php-zip php-intl php-curl php-gd php-mbstring php-bcmath mariadb-server composer unzip git
php -v
php -m | grep -E 'imap|intl|bcmath|zip|gd|mbstring|curl|xml|mysql'
composer --version
```

`php -v` prints 8.3 on Ubuntu 24.04 and 8.2 on Debian 12, and the `grep` lists each required extension.

> **Note**
>
> If Caddy is already running, it owns port 80 and Apache fails to start right after installation. That is expected; Step 6 moves Apache to a local port.

## Step 2 — Install Node.js for the asset build

Since Mautic 5, npm is required: the Composer project runs `npm ci` and builds Mautic's front-end assets during installation and every update. Mautic's official Docker image uses Node.js 24 from NodeSource, so install the same from NodeSource's apt repository:

```bash
sudo apt install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
```

```bash
NODE_MAJOR=24
sudo tee /etc/apt/sources.list.d/nodesource.sources <<EOF
Types: deb
URIs: https://deb.nodesource.com/node_${NODE_MAJOR}.x/
Suites: nodistro
Components: main
Signed-By: /etc/apt/keyrings/nodesource.gpg
EOF
sudo apt update
sudo apt install nodejs
node -v
npm -v
```

`node -v` should print a `v24` version.

## Step 3 — Tune PHP and create the database

Raise the PHP limits for the web server to the values Mautic's official image uses. The file path contains your PHP version, so read it into a variable first:

```bash
PHPV=$(php -r 'echo PHP_MAJOR_VERSION.".".PHP_MINOR_VERSION;')
echo $PHPV
sudo nano /etc/php/$PHPV/apache2/conf.d/99-mautic.ini
```

```ini
memory_limit = 512M
max_execution_time = 300
upload_max_filesize = 512M
post_max_size = 512M
date.timezone = UTC
```

`max_execution_time = 300` satisfies Mautic's minimum of 240 seconds. The command-line PHP used by Composer and cron keeps its own defaults, which have no execution time limit.

Generate a password for the database user with `openssl rand -hex 24`, then open the MariaDB shell as root (`sudo mariadb`) and create the database and user. Replace `change-me` with the generated password:

```sql
CREATE DATABASE mautic CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'mautic'@'localhost' IDENTIFIED BY 'change-me';
GRANT ALL PRIVILEGES ON mautic.* TO 'mautic'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```

MariaDB listens only on `localhost` in the default Ubuntu and Debian configuration, so it needs no firewall rule.

## Step 4 — Download Mautic with Composer

Mautic writes its configuration, cache, logs and media at runtime, so the whole project belongs to the web server user `www-data`, and every Composer and console command runs as that user. Composer and npm also need a writable home directory for their caches; give them `/var/lib/mautic-build`, which is outside the web root:

```bash
sudo mkdir -p /var/www/mautic /var/lib/mautic-build
sudo chown www-data:www-data /var/www/mautic /var/lib/mautic-build
cd /var/www/mautic
sudo -u www-data env HOME=/var/lib/mautic-build composer create-project mautic/recommended-project:^7.0 /var/www/mautic --no-interaction
```

`^7.0` selects the latest Mautic 7 release. The command downloads Mautic and its plugins and themes, runs `npm ci` and generates the assets, which takes several minutes. When it finishes, check the layout:

```bash
ls /var/www/mautic
```

You should see `bin`, `config`, `docroot`, `var` and `composer.json`. Only `docroot` is served to the web; configuration and logs stay outside it.

## Step 5 — Run the installer from the command line

Mautic also has a web installer, but it is reachable by anyone who finds the address before you finish. The command-line installer avoids that window. Run it as `www-data` with your public address, the database details from Step 3 and a strong admin password (Mautic requires a complex password since version 5.1):

```bash
cd /var/www/mautic
sudo -u www-data php bin/console mautic:install https://mautic.example.com --db_driver=pdo_mysql --db_host=localhost --db_port=3306 --db_name=mautic --db_user=mautic --db_password='change-me' --db_backup_tables=false --admin_firstname=Ada --admin_lastname=Admin --admin_username=admin --admin_email=admin@example.com --admin_password='Change-me-to-a-long-Passw0rd'
```

> **Tip**
>
> The passwords end up in your shell history. On Ubuntu and Debian, the default `.bashrc` ignores commands that start with a space, so type one space before `sudo` to keep this line out of the history.

The installer checks the requirements, creates the schema, loads the default data and creates the admin user. It stops with an error message if something critical is missing. Afterwards, `config/local.php` exists and holds the database settings and secret key; it belongs to `www-data` and is not inside `docroot`.

## Step 6 — Serve Mautic with Apache on a local port

Apache serves PHP with the `.htaccess` rules shipped in `docroot`; Caddy will sit in front of it. Move Apache from port 80 to `127.0.0.1:8080` and turn off the default site:

```bash
sudo sed -i 's/^Listen 80$/Listen 127.0.0.1:8080/' /etc/apache2/ports.conf
sudo a2dissite 000-default
sudo a2enmod rewrite setenvif
sudo nano /etc/apache2/sites-available/mautic.conf
```

Paste this virtual host. `AllowOverride All` activates Mautic's `.htaccess` rules, and the `SetEnvIf` line tells PHP that the original request used HTTPS when Caddy says so; only Caddy can reach this port, so the header can be trusted:

```conf
<VirtualHost 127.0.0.1:8080>
    ServerName mautic.example.com
    DocumentRoot /var/www/mautic/docroot

    SetEnvIf X-Forwarded-Proto "^https$" HTTPS=on

    <Directory /var/www/mautic/docroot>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/mautic-error.log
    CustomLog ${APACHE_LOG_DIR}/mautic-access.log combined
</VirtualHost>
```

Enable the site, test the configuration and restart Apache:

```bash
sudo a2ensite mautic
sudo apache2ctl configtest
sudo systemctl restart apache2
sudo ss -tlnp | grep apache2
curl -I http://127.0.0.1:8080/
```

`configtest` prints `Syntax OK`, `ss` shows Apache on `127.0.0.1:8080` only, and `curl` gets an HTTP answer from Mautic, typically a redirect to the login page.

## Step 7 — Add HTTPS with Caddy and set trusted proxies

Add a site block to `/etc/caddy/Caddyfile` and reload Caddy:

```caddyfile
mautic.example.com {
    reverse_proxy 127.0.0.1:8080
}
```

```bash
sudo systemctl reload caddy
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
```

Open `https://mautic.example.com` and log in with the admin account from Step 5. Then open **Settings** (the cog icon) → **Configuration** → **System Settings** and set:

- **Site URL**: `https://mautic.example.com`.
- **Trusted proxies**: `127.0.0.1`. Mautic's documentation calls this setting mandatory behind an SSL-terminating proxy; it also lets Mautic see the real visitor IP from Caddy's `X-Forwarded-For` header instead of `127.0.0.1`, which tracking relies on.
- **Trusted hosts**: `mautic.example.com`, so Mautic answers only to your own hostname.

> **Warning**
>
> Mautic's documentation warns that wrong trusted hosts or proxies can lock you out. If that happens, fix the values in `/var/www/mautic/config/local.php` and clear the cache with `sudo -u www-data php /var/www/mautic/bin/console cache:clear`.

## Step 8 — Schedule the cron jobs

Segments, campaigns and segment emails are processed only by cron jobs. Mautic lists the segment update, campaign update, campaign trigger, message queue and custom-field jobs as required, and recommends staggering them so they never start in the same minute. Create `/etc/cron.d/mautic` with `sudo nano /etc/cron.d/mautic`; each line runs as `www-data`:

```text
0,15,30,45 * * * * www-data php /var/www/mautic/bin/console mautic:segments:update --no-interaction --no-ansi
5,20,35,50 * * * * www-data php /var/www/mautic/bin/console mautic:campaigns:update --no-interaction --no-ansi
10,25,40,55 * * * * www-data php /var/www/mautic/bin/console mautic:campaigns:trigger --no-interaction --no-ansi
2,17,32,47 * * * * www-data php /var/www/mautic/bin/console mautic:messages:send --no-interaction --no-ansi
7,22,37,52 * * * * www-data php /var/www/mautic/bin/console mautic:broadcasts:send --no-interaction --no-ansi
12,42 * * * * www-data php /var/www/mautic/bin/console mautic:custom-field:create-column --no-interaction --no-ansi
13,43 * * * * www-data php /var/www/mautic/bin/console mautic:custom-field:delete-column --no-interaction --no-ansi
8,23,38,53 * * * * www-data php /var/www/mautic/bin/console mautic:import --no-interaction --no-ansi
3,33 * * * * www-data php /var/www/mautic/bin/console mautic:reports:scheduler --no-interaction --no-ansi
```

The first three timings come from Mautic's documentation; the others are spread over free minutes. `mautic:broadcasts:send` sends segment emails, `mautic:import` handles large CSV imports in the background, and `mautic:reports:scheduler` emails scheduled reports. Mautic documents further optional jobs, such as `mautic:email:fetch` for bounce handling and `mautic:webhooks:process` for queued webhooks; add them when you use those features. Run one job by hand to see its output, then confirm that cron picks the file up:

```bash
sudo -u www-data php /var/www/mautic/bin/console mautic:segments:update --no-interaction
journalctl -u cron --since "30 min ago"
```

## Step 9 — Connect an email service

Mautic sends email through Symfony Mailer with an SMTP DSN in the form `smtp://user:pass@smtp.example.com:587`. In **Settings → Configuration → Email Settings**, set the sender name and an address on a domain you control, then enter the SMTP host, port `587`, user name and password from your transactional email provider or SMTP relay; Symfony Mailer upgrades the connection on port 587 with STARTTLS. Publish the SPF, DKIM and DMARC records your provider gives you, or your messages will land in spam.

> **Note**
>
> Outbound port 25 is closed by default on HyperDC VPS. For services bought for a term of 3 months or longer, it is opened on request: [open a support ticket](/guides/support-tickets). Until then, send mail through an SMTP relay on port 587.

To test delivery end to end, create a segment that contains only your own contact, send it an email, and check that the message arrives and its links are tracked through `https://mautic.example.com`.

> **Tip**
>
> By default Mautic sends email immediately. For large lists, Mautic's settings let you switch the queue to the Doctrine transport and process it from cron with `php /var/www/mautic/bin/console messenger:consume email --time-limit=160`.

## Back up and restore

Mautic's state is the MariaDB database plus the project folder: `config/local.php` (database settings and secret key), uploaded media in `docroot/media`, and your `composer.json` and `composer.lock`. Dump the database with `--single-transaction`, which gives a consistent InnoDB snapshot without blocking Mautic, and archive the project without caches and `node_modules`:

```bash
sudo mkdir -p /opt/backups
sudo chown $USER:$USER /opt/backups
chmod 700 /opt/backups
sudo mariadb-dump --single-transaction --quick mautic | gzip > /opt/backups/mautic-db-$(date +%F).sql.gz
sudo tar czf /opt/backups/mautic-files-$(date +%F).tar.gz -C /var/www --exclude=mautic/node_modules --exclude=mautic/var/cache mautic
```

Keep copies of `/etc/apache2/sites-available/mautic.conf`, `/etc/cron.d/mautic` and the PHP settings file too. To restore, stop Apache, unpack the files, import the dump and clear the cache. Replace the dates with those of your backup:

> **Warning**
>
> Restoring overwrites the current Mautic files and tables. Make sure the backup files are complete before you start.

```bash
sudo systemctl stop apache2
sudo tar xzf /opt/backups/mautic-files-2026-10-09.tar.gz -C /var/www
sudo chown -R www-data:www-data /var/www/mautic
gunzip -c /opt/backups/mautic-db-2026-10-09.sql.gz | sudo mariadb mautic
sudo -u www-data php /var/www/mautic/bin/console cache:clear
sudo systemctl start apache2
```

On a new server, run Steps 1 to 3 and Step 6 first, restore, and then run `sudo -u www-data env HOME=/var/lib/mautic-build composer install` in `/var/www/mautic` to rebuild `node_modules`. Copy every backup off the server and test a restore regularly.

## Update Mautic

Mautic's update guide says never to update without a working, tested backup, and to check the release notes for new requirements such as a higher PHP version. The Composer constraint `^7.0` already allows every Mautic 7 release; for a new major version, first change the Mautic package versions in `composer.json` as the release notes describe. Then save the current Composer files, update, and finish with the database steps from the documentation:

```bash
cd /var/www/mautic
sudo -u www-data cp composer.json composer.json.bak
sudo -u www-data cp composer.lock composer.lock.bak
sudo -u www-data env HOME=/var/lib/mautic-build composer update --with-dependencies
sudo -u www-data php bin/console cache:clear
sudo -u www-data php bin/console mautic:update:apply --finish
sudo -u www-data php bin/console doctrine:migration:migrate --no-interaction
sudo -u www-data php bin/console cache:clear
```

If the update fails, restore the two `.bak` files and run `composer install` as above to return to the previous versions, then restore the database from your backup. The recommended project suggests keeping the whole folder in a Git repository, so `git diff` shows when an update changes scaffolded files such as `docroot/.htaccess`. Keep PHP, Apache and MariaDB patched with `sudo apt update && sudo apt upgrade`.

## Troubleshooting

### Apache fails to start with Address already in use

Another service, usually Caddy, already listens on port 80. Make sure Step 6 changed `ports.conf` to `Listen 127.0.0.1:8080`, check with `sudo ss -tlnp | grep -E ':80 |:8080 '`, then run `sudo systemctl restart apache2`.

### Composer stops because a PHP extension is missing

Mautic's Composer files require `ext-imap`, `ext-zip`, `ext-iconv`, `ext-pdo` and `ext-zlib`, plus the extensions on the requirements page. Install the missing `php-` package from Step 1, confirm with `php -m`, and run the Composer command again. On releases with PHP 8.4, `php-imap` is not available; use Ubuntu 24.04 or Debian 12.

### Login loops or Mautic builds http:// links

Mautic does not know the request came over HTTPS. Check the `SetEnvIf` line in the Apache site, set **Trusted proxies** to `127.0.0.1` and the **Site URL** to the `https://` address in System Settings, then clear the cache.

### Segments, campaigns or segment emails never run

The cron jobs are missing or failing. Check that `/etc/cron.d/mautic` belongs to `root`, has no dot in its name and ends with a newline, read `journalctl -u cron`, and run the failing command by hand as `www-data` to see the error. Application errors are logged in `/var/www/mautic/var/logs`.

### Emails are not delivered

Check the SMTP host, port, user name and password in Email Settings, make sure your provider has verified the sender domain, and read the newest log file in `/var/www/mautic/var/logs`. Outbound connections to your provider's port 587 must be allowed by any firewall between the server and the provider.

## Next steps

- Compare a lighter newsletter tool: [How to install listmonk](/guides/install-listmonk).
- Connect marketing to sales with [How to install Odoo](/guides/install-odoo).
- See server options for email marketing on the [Email marketing hosting](/email-marketing-hosting) page.
- Read Mautic's [cron jobs documentation](https://docs.mautic.org/en/7.0/configuration/cron_jobs.html) for every optional job and its options.

## Frequently asked questions

### Should I install Mautic with Composer or with Docker?

Mautic's documentation says that from Mautic 6 the default way to install, update and manage Mautic is Composer, which this guide follows. Official Docker images also exist, but their README asks you not to use the example setups in production without reviewing and configuring them first.

### Which PHP version does Mautic 7 need?

Mautic's requirements list PHP 8.2, 8.3, 8.4 and 8.5 for Mautic 7, and Mautic's Composer files require the imap, zip, iconv, pdo and zlib extensions. Ubuntu 24.04 ships PHP 8.3 and Debian 12 ships PHP 8.2, both with a php-imap package.

### Why are Ubuntu 26.04 and Debian 13 not covered?

Their PHP 8.4 packages no longer include an imap extension package, because IMAP was moved out of PHP's core, and Mautic 7 cannot be installed without it. Until that changes, use Ubuntu 24.04 LTS or Debian 12 for this method.

### Which cron jobs does Mautic need?

Mautic marks the segment update, campaign update, campaign trigger, message queue and custom-field jobs as required. Segment (broadcast) emails also need mautic:broadcasts:send. Mautic recommends staggering the jobs so they never start in the same minute.

### Can Mautic send email directly from the server?

Mautic sends through the SMTP server you set in its email settings. Outbound port 25 is closed by default on HyperDC VPS. For services bought for a term of 3 months or longer, it is opened on request through a support ticket. Until then, send mail through an SMTP relay on port 587.

### Which HyperDC servers can run Mautic?

Mautic asks for a VPS or dedicated server rather than shared hosting, so a HyperDC Linux VPS, VDS or dedicated server with root access and Ubuntu 24.04 LTS or Debian 12 fits. Size it for your contact database and campaign volume.

---

Source: <https://hyperdc.com/guides/tutorials/install-mautic>\
Updated: 2026-10-09