Best-practice discussion: How to setup a Mautic installation as project with Git?

Product Support
1

Hello everyone.

I’ve just installed a test project with DDEV following this blog-post. The only modification I made is to specify docroot: docroot inside of .ddev/config.yaml (I see this as absolute best practice to install a software to a public or docroot folder, instead of project-root, because we want to have a packages-folder for custom plugins, themes and other stuff, which are symlinked during deployment from there).

Here comes the problem:
If I make git init in the project-root, ALL installed files are added, (except vendor, but including docroot/*), because the default .gitignore does not expect a installation into a sub-folder. But even if I move the default .gitignore into docroot/ it has no effect, still everything is added to git.

If we modify the default .gitignore file to our structure, each composer update restores the original one (which apparently comes from the scaffold script). So we have to have also a customized scaffold version there? In any way, I’d prefer to keep the original .gitignore file in case of future updates. This all seems a bit confusing or complicated for a common project setup, so I’m curious how you doing this :slight_smile:

What is a best-practice here? How do you manage Mautic projects with git (without commiting everything what is loaded by Composer)?

Apprechiate any input or discussion here :pray:

Your software
My Mautic version is: 4.4.5
My PHP version is: 7.4
My Database type and version is: MariaDB 10.4

2

What we did was essentially clone mautic and change git to point to our local repo. We use docker instead of DDEV but that was a company choice. In regards to composer and custom work we done was put into Mautic’s plugins folder as there is no need to have a seperate packages folder not (App/Bundles but the folder called plugins. And made the necessary changes to gitignore so that it will be included in git.

Your plugins should have their own composer.json file. checkout neverbounce I think that does something along the lines of what you might be trying to do.

We decided against doing packages for our plugins as they are bespoke to what we do at the company. The majority overrides what mautic does in places to follow our own custom logic.

3

Thanks for your response. What feels a bit strange for me is the “duplication” of a lot of code (basically its a clone/fork of the original repository commited to you own one, right?). I understand that this is a reasonable way if you want to fully edit or customize files of the the Mautic core and other core bundles for one project.

So, two follow-up questions to your approach if you don’t mind:

  • How do you update Mautic? Just re-base changes of the official repo?
  • Does your approach comes from Mautic’s pre-composer time? (Means, is this officially still the recommended way to go)?

In general: if the Composer installation is the way to go from now on, IMO the Composer installation should fetch the vendor and Mautic core packages, e.g. fresh during a deployment. At least this is how I know it from other projects, where only(!) the custom plugins and project-settings incl. composer.json/-lock is checked into the project-repository :thinking:

4

Np I am happy to help. And I forgot to welcome you to the community :sweat_smile: so welcome lol!

I’ll answer your two questions first.

  1. Funny enough we have just upgraded to version 4.4.5 from version 3 - This was completed using the built in mautic terminal commands and the process I followed is
  • mautic:update:find to check that an update is needed.
  • mautic:update:apply which updates core mautic only
  • mautic:update:apply --finish which finishes the entire process.
    On this point, we created a separate branch and applied the update, and once we have tested that everything is working (which does require putting some code back) we will merge to our master deploy and run any migrations that would be needed on production. And of course we test everything on our staging server before going live.
  1. We actually started with Mautic 2 so our experience will be different to yourself but we have a dedicated dev team to work out kinks etc. What we do works for us, and is pretty common from what I have seen from other companies.

We try to limit core changes as much as possible unless its a bug fix. so when we do upgrade our version we limit the amount of maintenance that we actually need to do.

Now with composer, if you want to upgrade to say version 5, one of the steps that you would need to do is change the mautic version

from “mautic/core-lib”: “^4.0”, to “mautic/core-lib”: “^5.0”,

If any other changes are required here the mautic team will specify it in their upgrade guide

Take a look at symfony or laravel they show how they get devs to handle upgrades with composer really well.

Or if you are comfortable PM me and we can go through it on an online call as i find it easier to show rather then type lol

1 Like
5

And I forgot to welcome you to the community :sweat_smile: so welcome lol!

Thats very kind, thanks. Always happy to contribute too :hugs: I’m coming from Symfony and TYPO3 background, maybe that is where my confusion starts using Composer with Mautic (And maybe it is just a project-issue which I should report [resulting from a transformation-in-progress], but that is what I’m trying to figure out^^). Let me explain from the beginning:

Somewhere I’ve read that the installation via Composer is (or will be) the recommended way of installing it, which makes totally sense. The Docs also recomment using the mautic/recommended-project which gives us a full and ready-to-install composer.json (Depending on the system, Composer will already install everything).

Our project directory will contain the following structure:

project-root/
  - app/ (is empty, just contains a .htaccess file)
  - bin/
  - docroot/ (this is the public HTTP accessible folder containing the Mautic app)
  - vendor/
  - composer.json
  - composer.lock
  - .gitignore
  - ... (and some other files)

Now, if I run git init inside the project-root, followed by git status, it seems that EVERYTHING will be added to my repository, because Mautic’s .gitignore file might not be ready yet for setups using Composer (This just came into my mind while writing here).

What I would expect (from other project-setups) is ONLY adding the following files to my repo:

project-root/
  - composer.json (here I have to customize the project-name, e.g. "vendor/my-project")
  - composer.lock
  - .gitignore

With this setup, we would be able to create a packages folder (which is added to the repository), containing all project-related plugins and themes, each with an own composer.json. Composer will symlink them if installed to the project (or unlink them), which is very handy.

In case some core-files or other plugin-files must be modified/patched, we can make use of Composer-Patches providing some .diff files also added to the repository.

In my opinion this would be the most clean and reliable way to setup a project like this, especially without committing the whole Mautic core files (For sure, future updates have to be done by Composer as well).

Here is a .gitignore file which I had expected from the mautic/recommended-project:

/.DS_Store
/.idea/
/app/
/bin/
/docroot/
# private or sensitive data like credentials should be replaced by getenv(), then the local.php can be added to the repo as well
!/docroot/app/config/local.php
/vendor/
.env*
autoload.php
Gruntfile.js
package.json
package-lock.json

It excludes everything which comes from the Mautic packages, except the customized composer.json/-lock. All custom project-related files like packages/ or .ddev/ will be added to the repo.

Questions remain:

  • Is this a recommended Mautic setup?
  • Is it an error/issue from mautic/recommended-project, that Mautic’s default .gitignore is not compatible with this setup (yet)?
  • Even if I customize the default .gitignore like above, the scaffold will overwrite it on every Composer action. What is the recommended way to avoid it (probably also customize the docroot/app/assets/scaffold/files/example.gitignore file)?

As more I write here, I think it becomes more and more clear that probably it is a topic only for mautic/recommended-project… but nore sure?!

6

I just want to add that these are all my own opinions and the views expressed are my own and not of mautic

  • Is this a recommended Mautic setup?
    I don’t think it is. As you know being a developer it’s up to us how to set up as we see fit for our needs.
  • Is it an error/issue from mautic/recommended-project, that Mautic’s default .gitignore is not compatible with this setup (yet)?
    That I also don’t know but maybe @rchelsey can shed some light on that. But if you feel that it is then submit a bug or even do a PR for it.
  • Even if I customize the default .gitignore like above, the scaffold will overwrite it on every Composer action. What is the recommended way to avoid it (probably also customize the docroot/app/assets/scaffold/files/example.gitignore file)?
    Again I am not sure, I like to keep things simple (makes life so much easier) and it sounds like your over complicating. Is this a company policy to do what your trying to do?