Documentation on how this should be used with volumes

[that0n3guy]

We use docker for all our site deployments. We decided to not use any of these docker images but swiped some of the php scripts for setting up config files.

Some things I noticed that should be documented:

• This image is not for stateless use.
  • Setting your environment variables like MAUTIC_DB_HOST is kind of pointless because if you redeploy the container, your local.php will be lost and you have to "re-install" to get your secret_key again. If you put your local.php someplace in a docker volume, then you still don't need the mautic_db_host
  • local.php needs to be stored.
• media/files should be linked to a docker volume
• local.php should be linked to a docker volume

How to make this stateless:

• set db/mandrill into parameters_local.php instead of local.php (Separate secure config from non-secure config and support env variables in config mautic#886)
• document how to put the local.php someplace where it won't get wiped out
• probably need more env vars than db.

[mbabker]

Sorry, been busy as of late, but trying to comment on some stuff.

First, yes, the default for the image build is that the entire thing is stateless. Building it this way actually makes it usable as both a temporary testing box and a production system (with additional configuration). This is consistent with how the official Docker images for the CMS' (see WordPress and Drupal for example) are built too. The image here does make /var/www/html a volume by default (so the entire Mautic installation) which lets an user who is deploying an instance use Docker's configuration to map the volume.

The environment variables are really meant for helping with the initial deployment and not for persisting the configuration values. Those variables, if set, are prefilled into a stub local.php configuration file so that when you run Mautic's installer on a new deployment then the database credentials are pre-filled (you'd just need to re-enter the password). There is also logic in place so that a new deployment doesn't overwrite the local.php file if it already exists which lets the configuration persist if you've attached everything to an external volume.

I've done some testing of this image with this WordPress tutorial and the same concepts apply since the image was built pretty similarly to how that one is structured. So adding things into the documentation such as attaching an external volume should be relatively easy to accomplish (the README is basically a stub of what the official Docker library docs start off as).

As for the environment variables, right now I don't think there is a need for more to be used when deploying an instance. As I hinted at above, they're really meant to help quick start the install process, but once you've got Mautic running in the container then you'd manage it pretty much the same way as you would if it were on a web hosting account. Obviously as things change within Mautic the image's configuration can be updated to support them.

[that0n3guy]

I see the logic now. Thanks. I'm not a fan of the way most people do their wordpress/drupal dockerfiles. I don't think the whole app should be located in a volume since 99% of it is just app code and doesn't change, except for updates (also, drupal should be installed with make files, but thats a diff topic).

So I guess my suggestions above are only relevant if you don't use /var/www/html as a volume and instead use a volume for the files that are user updateable (like media/files and local.php.

[mbabker]

You could make an argument going both ways on the volume configuration. If you did volumes for only user content, in the case of Mautic we'd need volumes for the configuration, uploads, and plugins at a minimum (that's also assuming you're OK with stuff like the cache and logs not persisting, the latter might be questionable depending on what content is there). With the CMS' it just makes more sense in the long run to make the whole application a volume; with Mautic and the way it's structured it may be feasible to have separate volumes for those points that should persist since those directories are so few with our app structure.

[that0n3guy]

Yup. Thats what I was thinking. Plugins probably wouldn't need to persist either since they could be added by extending this dockerfile, or via env variable (like a link to the git repo, zip, etc...), or other method... Also, email themes would be the same way...

[Leopere]

+1
This definitely needs documented. Volumes not only for the Mautic app itself but also the Database would be ideal. It appears that the docker-compose.yml suggested in the README.md doesn't function out of the box.

[wittwerch]

I totally agree with @that0n3guy. The way most Dockerfiles are made for Drupal/Wordpress is pretty bad and we should rather stick to the Docker best practices.
In my opinion there are a few design problems in Mautic that makes it impossible today to run it in production using Docker. And by running in production in mean a stateless Docker container for Mautic that can be relocated, restarted, redeployed and scaled..

local.php
The configuration file is updated every time you change settings in the web UI. That means that you write state into your container, unless you somehow mount it using a volume.
I think that the local.php should only contain configurations that differ between stages (see http://12factor.net/config) and are necessary to run/start the application (like database settings). These settings should be read from environment variables. All other configuration should be stored in the database, so it's still changeable through the web UI but persists image redeploys.

Cloud Storage Bundle
The plugin to store assets on a cloud storage has a design flaw. It expects that you already have uploaded your asset to a S3 for example and Mautic just links to that asset. That requires that you uploaded the asset to S3 before using a 3rd party client.
Imho the upload part should be handled by Mautic transparently. It would be very handy for the marketing people they because must not be aware of S3 and the upload procedure. Plus we remove state from the Docker image because assets are stored outside.

And example in the Python world would be django-storages (http://django-storages.readthedocs.org/en/latest/)

[that0n3guy]

I know mautic has been updated a lot since this was created. Has anything changed in regards to this issue?

[mingfang]

Ideally I would like to bind mount one directory to store all the runtime settings.
e.g.

app/local
        /config/local.php
        /themes
        /idp
        /spool
        /media
              /files
              /images

Did I miss anything?
I would then simply bind mount app/local for each installation.

[mingfang]

If anyone is interested my Docker image is here https://github.com/mingfang/docker-mautic.git
I'm using paths_local.php to change the location of local.php.
The rest of the directories have be manually configured by the user to point to the "local" subtree above. I tried using parameters_local.php to override it but that has it's own problems so I gave up on it.

[hanselke]

is there an easy way to move all user files to a specific directory so we dont have to mount /var/www/html? 200+Mb isnt a lot but it seems hackish to mount it

[mingfang]

@hanselke My version https://github.com/mingfang/docker-mautic.git does not volume mount the entire /var/www/html, but only the user specific files under /var/www/html/app/local.

[hanselke]

hi @mingfang thanks for the reply.

Can i confirm that i just need to mount app/local as a volume?

[mingfang]

@hanselke Yes, please follow the instructions on my repo.

[that0n3guy]

@Gregy I see you just did some new docs in the readme. Still no mention of volumes (where are uploaded files stored, configs, etc...). Can you get those added?

[Gregy]

Hello, feel free to open a pull request with documentation changes. All help is welcome :)

[joaodalvi]

How to run this image as a stateless container? I can't figure out how to remove/recreate a container based on this image keeping the existing installation data. MySQL server and database database username and password are the same, through env variables, but everytime I recreate the container, it spins up the mautic installation again, and none of the changes made are reused on this new installation. Can someone help me?

[that0n3guy]

I think joaodalvi's issue is completely relevant to this issue. His question is exactly what this issue needs documented.

[joaodalvi]

Figured it out, after some good time. You have to create a volume for /var/www/html. This bit could be on the README, it would save people a LOT of time...

[that0n3guy]

@joaodalvi That's not really a solution either... that puts the whole mautic application in the volume.

[rdxmb]

@joaodalvi That's not really a solution either... that puts the whole mautic application in the volume.

There are better images doing that - but running updates with rsync instead of tar just seen at https://hub.docker.com/_/nextcloud/ . Maybe that application could be an example how to do it Docker-like - not only for volumes, but also with updating when using tags and other things like that.

By the way, this ticket is from 2015 - very long time....

[ArjonBu]

Will this issue ever get attention? Does anyone have an alternative how to do it? I created a mautic-operator for kubernetes https://gitlab.com/ArjonBu/mautic-operator but the persistent storage is not yet taken care of.

[that0n3guy]

Yeah, this is still a problem. @mingfang has an old docker image (see this line on his dockerfile That would change the config paths to a single location so you could just mount that as a volume.

I'm guessing (not tested) you could just mount the paths found here (https://github.com/mautic/mautic/blob/30909dcdc661951017917f402c96e80c219b7146/app/config/paths.php#L11) to volumes and it should work

[RCheesley]

@luizeof has this issue had any progress recently? Perhaps we can get to sorting out how we should work with volumes and document it appropriately so we can close this 4+ years old issue down?!

[luizeof]

Hello @RCheesley, Mautic is a little different from most apps that have already been designed for this microservice reality.

Volumes is the biggest example, by default, for a novice user (considering a novice who doesn't know how to handle docker volumes), by default, we use the entire / var / www / html folder. The whole application is there and it is much easier to change the image that only provides the environment (php, apache, etc.) and not the app itself.

There are people who prefer to put only the main file which is /var/www/html/app/config/local.php on a volume. However, if you send files to Mautic through the editor, it is necessary to create a volume for / var / www / html / media /, if you use third party plugins it would be necessary to create a volume to persist / var / www / html / plugins and if you customize twig themes, you have the volume / var / www / html / themes. Therefore, since the beginning of the docker-mautic, a single volume has been created to deal with all these folders that need to be persistent as can be read here https://github.com/mautic/docker-mautic#persistent-data-volumes

[luizeof]

Mautic is more than 4 years old and only now it seems that we have a viable and modern documentation area. I believe it is possible to create a specific area for Docker there now. Ping me at Slack.

[petersondmg]

Hello @luizeof, I would like just to share some thoughts

I think it would be nice not to depend on volumes for non system wide config options. It would be more flexible if some configs (interface configs) were stored on db itself.
Also for media files, maybe the ability to set a custom script to handle the files and upload on a CDN for instance, just keeping track of the files on db could remove the file system dependency also.
And for the plugins, maybe we could add them on build time on a certain directory instead of adding through the UI.

[luizeof]

Hello @petersondmg I believe this is related to Mautic itself and not to Mautic Docker. Mautic 3 has more features to make the container more effective.

[RCheesley]

@luizeof this is a super old issue and as we have an initiative specifically around improving the install/upgrade process and documentation I have created an issue here: mautic/mautic-documentation#159 to track writing and improving resources relating to the Docker-based installations.

Let's work on setting up some docs in the official documentation!