How to set up a Mautic instance for testing locally with DDEV

If you need to test something quickly with a clean Mautic instance, you can use the link https://gitpod.io/#https://github.com/mautic/mautic to spin up a Mautic instance based on our default branch. If you need to use a specific branch or tag, browse to that branch/tag in GitHub and copy the URL from the browser. Add this after the # in the URL. The default username will always be admin, and the password will be Maut1cR0cks!.

Setting up a local testing environment

Prerequisites

Before starting you will need a few pieces of software on your computer:

Docker Desktop
DDEV
Git
GitHub CLI (not mandatory but makes things much easier!)

Once you have these installed, we recommend that you use an editor such as Visual Studio Code which will allow you to interact with files, folders and the command line. There are other editors and Integrated Development Environments (IDEs) so if you already have one that you like, by all means use that!

Downloading Mautic

To start testing, we need to download a copy of Mautic for us to work with.

Before we do that, let's create a folder in your local computer where you'll locate all your local working environments. It's up to you where you save it and what you call it. Within that folder, create a folder where you'll work on this project - perhaps call it mautic4 for example.

Open your editor, and within the editor, open a terminal window.

In the terminal, we need to move into the directory we just created. Use the following commands (replace users/yourusername with the directory structure for your computer):

cd users/yourusername/myfolder/mautic4

If you need to move up an directory, for example back to /myfolder/, you can use the command:

cd ..

Once you are in the folder you want to work from, we need to pull down a copy of Mautic. To do this, we use a GitHub CLI command:

gh repo clone mautic/mautic

The first time you run this command, it will ask you to authenticate with GitHub. Just follow the steps, and once you've set up the authentication it won't bother you for some time.

This will pull down the GitHub repository at https://github.com/mautic/mautic to your local machine, ready for you to start testing with.

It may ask you to make a personal fork if you do not already have one - please use your personal account for the fork rather than an organization.

Setting up a local DDEV instance

Now we have the files locally, we need to move into the directory which was created using the command:

cd mautic

Now we need to spin up a server on our local computer, so that we can use PHP, MySQL and everything else that Mautic needs to run.

To do this, use the command:

ddev start

The first time you run this command it might take a little while to run through the process.

When you are prompted whether to install Mautic, choose yes.

This will install all the dependencies that Mautic requires to run, and will install Mautic with a default username and password:

username: admin password: Maut1cR0cks!

It will also install some software which allows you to capture outgoing emails, called Mailhog, PHPMyAdmin which enables you to view and interact with the database, and Redis Commander which allows you to interact with Redis where configured.

At the end of the ddev start command output, ddev will display some useful information as follows:

Once this process has completed, you will be able to access your local testing instance at:

https://mautic.ddev.site

Using developer mode

When testing Mautic, it is important that you are notified of any errors rather than having them output to the logs. We also don't want to have to constantly rebuild the Javascript and CSS files when changes are made.

For this reason, we use developer mode when testing in the Mautic Community.

By default, the preview window will open with developer mode, but if you lose it for any reason (you will notice the debug bar at the bottom disappear) just add index_dev.php to the URL:

https://mautic.ddev.site/index_dev.php