mautic/mautic installation guide

Install Mautic locally on macOS Tahoe (Apple silicon)

What you are installing

[Mautic](https://github.com/mautic/mautic) is an open-source, self-hosted marketing automation application written primarily in PHP. It provides campaign, segmentation, automation, and multi-channel marketing features while letting you operate the application and its database yourself.

**Relationship to Claude Code: unclassified.** The supplied repository metadata and first-party files do not document a Claude Code plugin, skill, hook, MCP server, or other Claude-specific mechanism. Mautic should therefore be treated as a standalone web application, not as a Claude Code extension.

This walkthrough covers a **local development/testing installation**, not a public production deployment. The repository explicitly says that its GitHub version is recommended for development and testing. It also warns that source outside a tagged release is considered alpha and may contain bugs or cause unexpected results, corruption, or data loss.

Before you begin

You need:

• A Mac with Apple silicon running macOS Tahoe.
• An administrator account when an installer requests approval.
• Internet access for downloads and dependency installation.
• Enough free storage for the repository, its downloaded dependencies, and application data.
• Familiarity with opening Terminal and pasting a command.

The supplied Mautic files do **not** state that macOS Tahoe or Apple silicon is supported, and they do not provide architecture-specific steps. Before continuing, open the repository’s README and follow its links for **installation requirements**, **supported versions**, and **Mautic Releases**. Confirm that the Mautic release and supporting software you intend to use are mutually compatible. Do not assume that the current default branch is production-ready merely because it is the branch shown first on GitHub.

You have two documented local source-installation routes:

1. **DDEV route:** the repository contains DDEV configuration. Mautic says starting it will launch the first-run process, install dependencies, and configure Mautic.
2. **Manual ZIP/Composer route:** download and extract the repository, run Composer to install packages, then finish through Mautic’s browser installer.

For a layperson, the DDEV route has fewer Mautic-specific manual steps. This guide therefore presents it first. The supplied files do not contain commands for installing DDEV or Composer themselves, so this guide does not invent any. Obtain those prerequisites only through the Mautic-linked documentation and the relevant first-party installer instructions.

Important choice: branch versus release

The metadata identifies `7.x` as the repository’s default branch. Mautic warns that code outside a tagged release is alpha. For anything beyond disposable local evaluation, use a version listed on the project’s **Mautic Releases** page and verify it against the linked supported-version information.

For a real production system, stop here and use the pre-packaged production download from [mautic.org/download](https://www.mautic.org/download), or follow Mautic’s documented Composer production installation. The project specifically recommends those options for production. A production deployment also involves a suitable web root, database, server configuration, ongoing maintenance, and safe updates; the supplied files do not provide enough detail for a responsible Tahoe production recipe.

Route A: local installation with DDEV

1. Install DDEV using the linked first-party guidance

From the Mautic README, open the linked DDEV-for-Mautic documentation. Install DDEV as described there. Because no DDEV installation command is included in the supplied repository evidence, none is provided here.

Do not continue until DDEV is installed and available to Terminal.

2. Download Mautic from GitHub

1. Open [github.com/mautic/mautic](https://github.com/mautic/mautic).
2. Select the tagged release or branch you decided to test.
3. Use GitHub’s **Code** menu and choose **Download ZIP**.
4. Open the downloaded ZIP in Finder to extract it.
5. Move the extracted folder somewhere easy to find, such as a folder under your home directory.

Using Finder avoids adding undocumented shell commands merely to download or navigate to the repository.

3. Open Terminal in the extracted folder

In Finder, open the extracted Mautic folder. Use macOS’s Finder service for opening a Terminal window at that folder. The exact wording can vary with macOS settings; the goal is for Terminal’s current location to be the folder containing the Mautic source and its DDEV configuration.

4. Configure the DDEV project

Paste this repository-documented command and press Return:

ddev config

Read every prompt before accepting or changing a value. The supplied README documents this command but does not specify prompt answers for macOS Tahoe, so this guide does not guess them.

5. Start the project

After configuration completes, paste:

ddev start

Mautic states that this starts its first-run process, automatically installs dependencies, and configures Mautic for use. Keep Terminal open while it works. Initial setup can require downloads, so completion time depends on your connection and Mac.

If Terminal reports an error, do not substitute random commands from third-party posts. Record the exact message and use the support resources listed below.

6. Open Mautic

When startup finishes, inspect DDEV’s displayed output for the local project address and open that address in your browser. Complete any first-run screens that appear. Use test information rather than real contacts, live email credentials, or production customer data while evaluating an alpha/development source installation.

A successful result is a locally reachable Mautic interface with its first-run configuration completed.

Route B: manual ZIP installation with Composer

Use this route only if you already have a web environment and Composer that satisfy the Mautic release’s linked requirements. Mautic explicitly says Composer must already be available because it downloads the vendor packages.

1. Download and place the source

Download and extract the chosen repository ZIP as described above. Mautic says to extract it to your web root. Determining a correct web root and configuring a PHP web server are environment-specific tasks not documented in the supplied files, so no unsupported server commands are included here.

2. Open Terminal in the Mautic folder

Use Finder to open Terminal at the extracted source folder. Confirm visually that this is the Mautic project folder before installing dependencies.

3. Install required packages

Paste the one Composer command documented by the repository:

composer install

Wait for Composer to finish. Do not close Terminal during the operation. If Composer reports that PHP, an extension, or another requirement is missing or incompatible, return to Mautic’s linked requirements and supported-version pages rather than forcing installation or bypassing checks.

4. Complete the browser installer

Start or use the already configured web environment that serves your chosen web root, then open its Mautic address in a browser. The repository directs users to finish installation through the web installer. Supply the database and site details appropriate to that preconfigured environment. The evidence does not define database names, credentials, ports, PHP versions, or web-server commands, so this guide deliberately does not invent them.

Verification and safe next steps

After either route:

1. Confirm that the Mautic page loads locally without an error screen.
2. Confirm that you can sign in with the administrator account created during first-run setup.
3. Explore with sample contacts and campaigns before connecting email providers or importing personal data.
4. Read the [Mautic user documentation](https://docs.mautic.org) before configuring campaigns.
5. Read the [developer documentation](https://devdocs.mautic.org) if you plan to modify code or use the API.

Do not treat a loading dashboard alone as proof that email delivery, scheduled automation, upgrades, backups, or production security are configured. Those topics are outside the supplied installation evidence.

Troubleshooting and limitations

• **DDEV does not start:** preserve the exact Terminal output and consult the Mautic DDEV documentation linked from the README.
• **Composer is not found:** Composer is a stated prerequisite for the manual route. Install it through the project-linked and Composer first-party guidance; no repository-supported installation command was supplied here.
• **Composer reports incompatibility:** check the release’s requirements and supported versions. Do not bypass the check.
• **Browser installer does not appear:** verify that your web environment points to the extracted Mautic web root. The repository does not supply a Tahoe-specific web-server procedure.
• **Update problems:** Mautic warns that source and database schemas can fall out of sync and that the release updater may then fail, requiring manual updates.
• **Production use:** prefer the pre-packaged Mautic download or the project’s documented Composer production route instead of an untagged GitHub source checkout.

For help, use the project’s [GitHub Issues](https://github.com/mautic/mautic/issues), [community forum](https://forum.mautic.org/), user documentation, or developer documentation. When asking for help, include your selected Mautic release, that you are using macOS Tahoe on Apple silicon, which route you followed, and the exact error text—without posting passwords, API keys, database credentials, or personal contact data.