Full guide to permissions in Mautic

In this tutorial you’ll understand what Mautic cache is, how to deal with file permissions, and how to regenerate assets.

Mautic is based on Symfony, a framework, that helps to develop applications faster and more reliable. The software written this way needs an under the hood manual or map if you like, that makes sure the different parts know how to play together. This manual is not for users, not even for developers, but for the software itself. It tells one part of the software how the other part supposed to work.

I’m sure you used GPS before. Sometimes when you drive someone the route has to be replanned because the road conditions change. Similarly this manual inside Mautic has to be rewritten as well. This is clearing the cache.

The cache folder sits here:

/var/cache

If you want to ‘throw away your old map’ and ‘draw a new one’ you can do it by clearing the cache. Mautic will automaticaslly regenarate it for you. You can do it with this command after you navigated to your cache folder above:

rm -rf var/cache/*

In some tutorials you might see this command for clearing the cache:

php bin/console cache:clear

This is usually a good advise, but running the command above can go terribly wrong. And this is because of the permissions. It’s super important that the right “person” is issuing the commands. Let me explain.

There are a bunch of programs running on your computer. These programs are running in the name of different virtual users. Not every virtual user has the same permissions. Similar to real life: you don’t want a cook to make an open heart surgery.

So there is one virtual user who is responsible for running the web-show. This user runs your webserver most likely apache or nginx. You can actually see what the name of this virtual user is. Try:

ps aux | egrep '(apache|httpd)'

You’ll see an output like this:

www-data  16738  0.0  0.2 531464 63356 ?        S    06:25   0:02 /usr/sbin/apache2 -k start

Or in case of Nginx, you might wanna try

ps aux | egrep 'nginx'

You’ll get an output like:

www-data   239  0.0  0.0 145992  4048 ?        S    Feb18  33:19 nginx: worker process

In both cases above a user called www-data is running your web activities. In order to do that, this user has to have access to all the files in your web folder. If the user has no permissions, that is similar to locking out a cook from a kitchen.

So when you regerate your cache and run the php bin/console cache:clear command NOT as the www-data user, but for example sudo user you can run into problems. Sudo is the post powerful user on the server, and this command is the equvalent of the hotel director rewriting all the recipes, but not letting in anyone into the kitchen under his ranks.

The similar thing is happening with scheduled tasks.

In order to run background commands with Mautic, you need to set the up in the crontab. If you add the commands to the wrong virtual user’s crontab it will be executed in the name of the wrong user.

Each file’s and folder’s permission is visible, you can see it by running the following command:

ls -la

This will list your directory and the files in it. The permissions and owners will be visible for each file:

-rwxr-xr-x  1 www-data www-data       646 Oct  1 14:24 index.php

You can read more about permissions here, bit I’ll keep it short:

You need to make sure, that the files belong to your webserver user, and they are rewritable. Don’t just update or clear the cache in the name of any user. Especially if you are logged in as sudo. That is the equivalent of running around with two active nuclear warheads ducktaped to your arms in a porcelaine store while walking on lego blocks.

Even if you are sudo user, you can issue the commands as www-data user by using this format (use the right path to your Mautic):

sudo -u www-data php /var/www/html/mautic/app/console cache:clear

Once your permissions are already messed up, you can any time fix it. Go to your Mautic folder, and:

find . -type f -not -perm 644 -exec chmod 644 {} +
find . -type d -not -perm 755 -exec chmod 755 {} +
chmod -R g+w var/cache/ var/logs/ app/config/
chmod -R g+w media/files/ media/images/ translations/
rm -rf var/cache/*

This is like a general fix, you can run any time you have an issue with “unable to write” or “cannot be found” type of errors.

You can also regerate the cache by warming it up. It can give you additional errors that might help:

sudo -u www-data php bin/console cache:warmup

If it gives you a nice green output, than everything should be okay:

[OK] Cache for the "prod" environment (debug=false) was successfully warmed. 

We are almost done. Symfony also works with assets. These are not inclided in the cache, and you might need to regenerate them from time to time, after update when big changes have happened in the background.

This solves issues like previously working fictions not working, like dropdown in segments.

You can easily do it by issueing the right command:

sudo -u www-data php bin/console mautic:assets:generate

This will combine and minify asset files from each bundle into single production files. In other words: resets big changes.