MOVED TO https://lab.civicrm.org/michaelmcandrew/civicrm-buildkit-docker
CiviCRM buildkit on Docker is thin wrapper around CiviCRM's buildkit, allowing it to be run in a docker container.
Note: CiviCRM buildkit is primarily a development tool - it is not designed for production hosting. If you are looking for CiviCRM docker containers designed for hosting, see https://lab.3sd.io/tools/civicrm-buildkit.
The docker image at https://hub.docker.com/r/michaelmcandrew/civicrm-buildkit/ is built with the civicrm/Dockerfile in this repo and published nightly. It requires another container running MySQL. You may wish to use it with other containers like phpmyadmin and maildev.
The docker-compose.yml file in this repository is a good starting point for a Docker-based CiviCRM development environment.
- Ensure you meet the requirements (
dockerandgit) - Clone this repository
- From the repository root, run
docker-compose up -dto start the containers defined in thedocker-compose.ymlfile - Create a WordPress demo site with
docker-compose exec -u buildkit civicrm civibuild create wp-demo - Navigate to your new CiviCRM development site at http://dmaster.localhost:7890
In order to 'interact' with your codebase with command line tools such civix etc, you'll need to run a bash shell 'within' the container. Launch a bash shell in the container with docker-compose exec -u buildkit civicrm bash.
Most issues that people report with CiviCRM buildkit on Docker turn out to be CiviCRM buildkit issues - please consult the Buildkit documentation.
Login to a bash shell in the container: docker-compose exec -u buildkit civicrm bash
Execute a command in the container docker-compose exec -u buildkit civicrm <COMMAND>
The build directory of this repository is mounted into the civicrm container at /buildkit/build. Builds created in the container will be visible here which allows files to be edited directly on the host.
You may notice that all the files that buildkit creates in the build directory are gitignored. This makes sense from this repositories point of view, but can be annoying if you are working on files in this directory. For example, in Visual Studio Code these files appear greyed out and are excluded from search results.
As a workaround, you may want to open the build directory directly. It has a .vscode folder that requests that vscode ignores the git repository in its parent folder, hence files do not appear greyed out.
The container includes and configures the Xdebug php extension. See civicrm/docker-civicrm-entrypoint for the relevant configuration.
The build directory also contains the relevant configuration for Visual Studio Code (in the build/.vscode/launch.json file). All you should need to do is install the Visual Studio Code Xdebug extension.
We mount the extra directory of this repository at /extra in the container for ad hoc use.
By default, new builds created with this Docker image are created at http://[SITE_NAME].localhost:7890. This makes it simple to create multiple builds in the same container.
Other URLs can be passed to the civibuild command, however, you will need to ensure any domains are resolved appropriately, e.g. by adding entries to the /etc/hosts file.
The default docker-compose.yml configuration includes phpMyAdmin which should be available at http://localhost:7891.
The default docker-compose.yml configuration maildev which should be available at http://localhost:7892.
Maildev will collect all email sent from the civicrm container.
Note: by default, buildkit disables outbound mail. We delete civicrm-buildkit/app/civicrm.settings.d/100-mail.php which re-enables outbound mail, install msmtp on the civicrm container, and configure it to deliver all mail to the maildev container.
We aim to support all current versions of PHP. You can see currently supported versions here: publish/include.php. Please let us know if we are out of date.
See publish/README.md for instructions on using CiviCRM containers that use different versions of PHP.
The mounts we use for /buildkit/build and /extra share UIDs and GIDs between the host and container. The container expects them to both be 1000. If you want to use a different UID or GID (e.g. because your user does not have a UID and GID of 1000, you can create a custom image that passes BUILDKIT_UID and BUILDKIT_GID as arguments.
This repository comes with a docker-compose-build.yml that can be used for building custom images. Create a custom build with a custom UID for the buildkit user as follows:
- Overwrite
docker-compose.ymlwith the contents ofdocker-compose-build.yml. - Change the BUILDKIT_UID argument to match your user id if necessary (
echo $UIDshould give you your user id). - run
docker-compose up -d --build.
Ask any questions you have in the docker chatroom (feel free to @michaelmcandrew if you like), or file an issue in the github issue queue.
New docker images are released nightly on Docker Hub at https://hub.docker.com/r/michaelmcandrew/civicrm/. Upgrade to the latest version as follows:
docker pull michaelmcandrew/civicrmto download the latest images.docker-compose up -dto restart your containers with the latest image.
The docker-compose.yml defines the following containers:
- civicrm (serves the sites; contains build and admin tools like
civibuild,cv,civixetc.) - mysql
- phpmyadmin for easier MySQL admin
- maildev to catch outbound email
We stick with the defaults and follow best practice whenever possible. When CiviCRM best practice and Docker best practice are in conflict we typically have to do things the CiviCRM way and make a note in the 'cloud native' project of the steps we could take to make CiviCRM more Docker friendly (e.g. environment variables to configure SMTP).
More general discussion about CiviCRM and Docker is welcome in CivCRM's 'cloud-native' project.
Windows is not officially supported. Please get in contact if you would like to help with support for windows. That said, here are a few notes that might be helpful.
There is an issue with file permissions if you are using Windows. Follow these instructions for enabling WSL2 integration and upgrading an existing WSL installation to WSL2. Background on the issue #52.
CiviCRM Buildkit Docker is maintained by Michael McAndrew of Third Sector Design who you can contact for help, support and further development.
Contributions to this repository are very welcome! Feel free to submit a pull request for minor improvements. For larger changes to reduce it probably makes sense to create an issue first.
See Publishing Dockerfiles for details on how to update the image published on https://hub.docker.com.
This extension is licensed under AGPL-3.0.