ARCHIVED! Don't use this.
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., (*1)
Docker Scaffolding for Drupal 8
, (*2)
Purpose
This repository provides two artifacts:, (*3)
- 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-project composer.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.
Usage/Quick-Start
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., (*4)
Default addresses and command examples
- Start for first time; create data container, install Drupal:
docker-compose up
- Web:
http://localhost:8082
- Get a login for uid 1, after install:
docker-compose exec web drush uli (See below for shortcut options)
Features
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 and development.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 and development.services.yml
+ 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 runs composer 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
and HTPASSWD_PASSWORD environment variables are set, e.g., for a
staging site. (Or mount in your own /etc/.htpasswd file to use.), (*5)
Why ship with Xdebug? Won't it waste resources in production?
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., (*6)
Development Workflow
TL;DR: Leverage composer as much as possible for managing your project. The
drupal-project README is very helpful on this point (see above.), (*7)
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., (*8)
Development Mode
Enable development mode (on by default) by setting the ENVIRONMENT environment
variable == DEV., (*9)
Version control notes
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., (*10)
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., (*11)
ddrush helper script
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., (*12)
Xdebug Usage on same host as Docker 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!, (*13)
Updating Drupal core
drupal-project's post-install command will ensure your Drupal core "scaffolding"
files are kept in sync with upstream. See drupal-project's README., (*14)
What about Drupal 8 configuration?
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., (*15)
Patching
Check out composer-patches for an easy
solution., (*16)
Configuration management in development mode
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., (*17)
Database management in development mode
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., (*18)
SSL Support
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., (*19)
Production Deployment
Data Permanence
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., (*20)
Requirements
Highly Recommended
-
direnv for zero-config use of
ddrush drush wrapper and scripts in vendor/bin.
Contributing
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., (*21)
Known Issues
See the confirmed bugs in the issue queue., (*22)
See Also
Other Projects
There are a few other Drupal/Docker projects, though most appear focused on Drupal 7:
- dropdock
- drude
- bowline, (*23)
Groups and Resources
Copyright and License
© 2016-2018, Brad Jones LLC. Licensed under GPL 2., (*24)
Wallogit.com
