It was nice while it lasted but Composer and Docker have come a long way, and this repository is a vestige of a bygone era. Things are simpler now - use drupal/recommended-project
et. al.
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.json
file derived from drupal-project to pull in Drupal core, and provides additional helpful Docker-focused functionality. The drupal-projectcomposer.json
file 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 PROJECT-DIR
.
- Start for first time; create data container, install Drupal:
docker-compose up
- Web:
https://localhost:8082
- 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.
- A
Dockerfile
that 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
settings.php
,settings.local.php
anddevelopment.services.yml
files.
- Scripts respond to environment variables, with defaults in the docker-compose.yml file:
- In development mode, enables Xdebug for Apache, and
toggles inclusion of
settings.local.php
anddevelopment.services.yml
- 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/etc/drush/drushrc.php
file.dbash
, a shortcut for getting a bash shell inside the web container (as www-data)
- An
.envrc
file, for use with direnv, that:- Tells wrapper scripts the correct container to execute against (by pattern).
- Includes the wrapper script and the
vendor/bin
directory into the PATH.
- Xdebug for development, and all invocations of the
ddrush
helper script .dockerignore
excludes VCS and uploaded files. Docker runscomposer install
inside 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_USER
andHTPASSWD_PASSWORD
environment variables are set, e.g., for a staging site. (Or mount in your own/etc/.htpasswd
file 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
commands like 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
outside the 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 ENVIRONMENT
environment
variable == DEV
.
The proper way to include projects and other dependencies, when using composer,
is to add them as requirements in composer.json
and then running composer update
.
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 dbash
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 config/drupal/sync
.
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,
then the drupal_data
container.
SSL termination is no longer bundled. In the spirit of Docker containers doing one task well, consider using a proxy container in conjunction with a free Let's Encrypt certificate.
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 web-writeable.txt
so user and system-generated files are preserved.
- Docker
- 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
ddrush
drush wrapper and scripts invendor/bin
.
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.