Project template for Drupal 8 with Composer and Docker
This repository provides two artifacts:
- A Composer package intended for one-time, initial scaffolding of a new
Drupal 8 project, which would then be self-contained.
It uses a
composer.jsonfile derived from drupal-project to pull in Drupal core, and provides additional helpful Docker-focused functionality. The drupal-project
composer.jsonfile and helper scripts can then be used to manage core updates, contrib modules and more. Drupal 8, with its robust exportable configuration file management and Composer integration, is uniquely suited for containerized development.
- A Docker image tailored for use with the enclosed project scaffolding. Its
behavior is largely dictated by the files in
config/docker/web/base, however they may be overridden on a project-specific basis by copying over the files at the appropriate destination. Use this image at your own risk, understanding that backwards-compatibility in your particular case may not be guaranteed. For safest results, build your own base images.
composer create-project --stability dev --no-interaction --ignore-platform-reqs bradjonesllc/docker-drupal:^2 PROJECT-DIR
...Will install into a new directory named
- Start for first time; create data container, install Drupal:
- Get a login for uid 1, after install:
docker-compose exec web drush uli(See below for shortcut options)
Your new Drupal 8 site comes with a number of helper scripts and config files that speed development in a containerized environment and production deployment.
Dockerfilethat includes all required PHP extensions for Drupal 8
- A quick-start Docker Compose file, which provides an Apache/PHP web container, mysql container and data volume.
- Site installation with:
- Optional force-set of an existing site UUID and import of configuration files, if present.
- Sensible default
- Scripts respond to environment variables, with defaults in the docker-compose.yml file:
- In development mode, enables Xdebug for Apache, and
toggles inclusion of
- In development mode, enables Xdebug for Apache, and toggles inclusion of
- Wrapper scripts:
ddrush, for executing drush inside the web container, with a starter global
dbash, a shortcut for getting a bash shell inside the web container (as www-data)
.envrcfile, for use with direnv, that:
- Tells wrapper scripts the correct container to execute against (by pattern).
- Includes the wrapper script and the
vendor/bindirectory into the PATH.
- Xdebug for development, and all invocations of the
.dockerignoreexcludes VCS and uploaded files. Docker runs
composer installinside the container on build, though if your development environment includes many of those files, having them copied into the container saves some time on build. See Development Workflow, below.
- All processes in the web container log to
STDOUT; this is useful if you wish to aggregate your Docker container logs or integrate with an external log service.
- Default configuration files for PhpStorm, including a server configuration and path mapping for Xdebug and setting max debug connections == 10 for compatibility with Drush's subrequests.
- A default cron implementation via crontab, which runs only when not in development mode.
- Support for site-wide HTTP Basic authentication when the
HTPASSWD_PASSWORDenvironment variables are set, e.g., for a staging site. (Or mount in your own
/etc/.htpasswdfile to use.)
Xdebug is not loaded/started when in development mode (see below), so while you are shipping a slightly-larger container, this setup avoids the need for a "Development-only" Dockerfile.
TL;DR: Leverage composer as much as possible for managing your project. The drupal-project README is very helpful on this point (see above.)
While a wrapper is provided for running drush inside the container, avoid using
drush dl. When using the default
docker-compose.yml file, we
inject the entire file structure on the host into the container, so your local
file changes are reflected in real time. Asking drush to make filesystem changes
sites/*/files directory (
drush cache-rebuild should be OK) may
result in permissions errors and other weirdness.
Enable development mode (on by default) by setting the
The proper way to include projects and other dependencies, when using composer,
is to add them as requirements in
composer.json and then running
As noted above, the contents of those dependencies are excluded by default in
.gitignore, so you should only be versioning code custom to your site.
Paired with the environment variable/PATH set with direnv (see above), you may execute
most Drush commands inside the web container by typing
ddrush your-command inside
the project. (You may need to run
direnv allow) in your shell, before starting work.
More complex commands involving quoting are not passed through verbatim; run
first, then your
drush command directly inside the container.
Toggle Xdebug in your browser or HTTP request, and initiate a corresponding listening session in your IDE on port 9000. The provided PhpStorm configuration means you can just click the phone icon and go!
drupal-project's post-install command will ensure your Drupal core "scaffolding" files are kept in sync with upstream. See drupal-project's README.
To ship/version a copy of your site with exported configuration, dump the config
to disk -
ddrush config-export - and your config will be dumped to
That directory is set as writable by the Apache user in development mode, for ease
of export. In a production environment, import your configuration with drush or the web UI.
Check out composer-patches for an easy solution.
When the web container starts in with the environment variable
DRUPAL_INSTALL = TRUE,
the bootstrap script attempts to determine the presence of an installed Drupal database.
If not found, the script will attempt to install Drupal, set the site UUID, and import
any existing configuration. Thus you can re-use (or, not) a development database even
across web container rebuilds.
As noted above, the bootstrap script contains some safeguards against installing
over an existing database. Should you wish to (re-)start from scratch (or a fresh
import of your exported configuration files), remove the
db database container,
With development mode off, Drupal will expect to find an installed database at the
db alias. Also, it's strongly suggested you mount host directories into the container
at the locations in
so user and system-generated files are preserved.
- Docker Compose, for running containers locally.
- Linux or similar virtualized environment with bash shell. Perhaps Docker Toolbox will help if you're on Windows or Mac?
- A local installation of composer
- direnv for zero-config use of
ddrushdrush wrapper and scripts in
Issues and pull requests welcome; Both Drupal 8 and Docker are relatively new and fast-moving projects. There doesn't appear to be many other comprehensive starterkits for Docker and Drupal, so this is my effort at helping others avoid my steep learning curve on this front.
See the confirmed bugs in the issue queue.
There are a few other Drupal/Docker projects, though most appear focused on Drupal 7:
© 2016-2018, Brad Jones LLC. Licensed under GPL 2.