Docker image - design principles and scope
This text is draft - feedback welcome
We are creating CiviCRM Docker image designed to be used as a building block in the production hosting of CiviCRM (see #5064 for more details). It will support both CiviCRM Standalone and CiviCRM alongside a CMS.
We expect the image to be used as part of a wider set of tools to create reliable, performant, scalable hosting infrastructure. Creating that infrastructure is outside of the scope of this image and we are agnostic on what tools used to do so. Commonly used tools include Kubernetes, Docker swarm, etc.
The image can also be used as part of a development environment to enable 'dev prod parity'. When we say development environment we are referring specifically to a development environment for production hosting, not a development environment for core CiviCRM development (buildkit etc.).
Note: we will likely encounter limitations in making each CMS 'Docker friendly' that are outside of our control.Note: support for core development workflows (buildkit, etc.) is outside of the scope of this project.
It is based on the following principles:
No surprises. We'll follow the well trodden path. Use CiviCRM defaults and recommendations, and Docker and cloud best practices, e.g. https://12factor.net/. There are many different opinions about the best way to deploy CiviCRM and we won't be able to please everyone. If you want to do something extra special or clever, then this might not be for you.
Be conservative about options. Each option that we add multiplies complexity and increases the chance of bugs and breakages and we'll avoid adding them unless there is a compelling reason. That said, where possible we'll design the image in such a way that it can be used as a base for more opinionated solutions (e.g. by breaking the Docker image into layers).
Build process
A possible architecture is as follows:
- Layer 1: CiviCRM Dependencies and tools
- Layer 2: CMS/standalone dependencies and tools
- Layer 3: Application source code
Consumers can choose the image that is the most appropriate jumping off point for their infrastructure.
We expect many consumers of this repository will roll their own Layer 3 that makes sense for their own own build process. A simple approach to building a Layer 3 would be to copy a source code tree from a repository. Other options include using CMS tools such as drush
or wp
or dependency managers like composer
.
We could consider swapping the order of Layers 1 and 2 and rely on official CMS builds as the base layer. This would save time but mean we were reliant on the upstream base images and need to deal with any variance between them. It is worth noting that the Drupal and WordPress images on Docker hub are maintained by the Docker community, not the projects themselves.
Configuration
We should consider patching CiviCRM to allow it to consume settings passed as environment variables (or similar).
Backing services
All 'backing services', including MySQL, email delivery, payment providers, etc, are outside the scope of this image and are expected to be configured via environment variables or similar.
We may consider creating recommended images for backing services (e.g. MySQL, email services) further down the line.
Admin processes
We will include existing tools like cv
and civix
to assist with the execution of one off admin processes (e.g. upgrades, config changes, etc.) These tools are also useful during development.
There are some admin processes, e.g. backups, snapshots, for which there are currently no official tools. We should consider creating these as part of this project.
We may also include cron for scheduled tasks.
Port binding
The image wil expose CiviCRM (and the CMS via http on a specific port. Reverse proxies, caches, firewalls, etc. are outside of the scope of this project.
Concurrency
The image will be designed to support horizontal scaling, i.e. running multiple instances of the image in parallel.
Logs
All logs (CiviCRM, Apache, PHP) will be sent to stdout/stderr.