From 7f751b904114f358af9bc5cde8bcb961a1795a53 Mon Sep 17 00:00:00 2001
From: Tianon Gravi <admwiggin@gmail.com>
Date: Wed, 25 Jan 2017 15:26:01 -0800
Subject: [PATCH] Add some notes about volumes in Drupal, especially updating
 "docker-compose.yml"

I tested this by using `docker-compose up -d`, going through Drupal's web-based setup process to get Drupal fully configured and operational, then used `docker-compose up -d --force-recreate` to force both containers to be re-created (which works very hard to keep the volumes), and verified that my site was still configured and working properly.
---
 drupal/content.md         | 35 +++++++++++++++++++++++++++++++++++
 drupal/docker-compose.yml | 11 ++++++++++-
 2 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/drupal/content.md b/drupal/content.md
index e5c339273..1747c5b44 100644
--- a/drupal/content.md
+++ b/drupal/content.md
@@ -46,6 +46,41 @@ $ docker run --name some-%%REPO%% --link some-postgres:postgres -d %%REPO%%
 -	Database name/username/password: `<details for accessing your PostgreSQL instance>` (`POSTGRES_USER`, `POSTGRES_PASSWORD`; see environment variables in the description for [`postgres`](https://registry.hub.docker.com/_/postgres/))
 -	ADVANCED OPTIONS; Database host: `postgres` (for using the `/etc/hosts` entry added by `--link` to access the linked container's PostgreSQL instance)
 
+## Volumes
+
+By default, this image does not include any volumes. There is a lot of good discussion on this topic in [docker-library/drupal#3](https://github.com/docker-library/drupal/issues/3), which is definitely recommended reading.
+
+There is consensus that `/var/www/html/modules`, `/var/www/html/profiles`, and `/var/www/html/themes` are things that generally ought to be volumes (and might have an explicit `VOLUME` declaration in a future update to this image), but handling of `/var/www/html/sites` is somewhat more complex, since the contents of that directory *do* need to be initialized with the contents from the image.
+
+If using bind-mounts, one way to accomplish pre-seeding your local `sites` directory would be something like the following:
+
+```console
+$ docker run --rm %%REPO%% tar -cC /var/www/html/sites . | tar -xC /path/on/host/sites
+```
+
+This can then be bind-mounted into a new container:
+
+```console
+$ docker run --name some-%%REPO%% --link some-postgres:postgres -d \
+	-v /path/on/host/modules:/var/www/html/modules \
+	-v /path/on/host/profiles:/var/www/html/profiles \
+	-v /path/on/host/sites:/var/www/html/sites \
+	-v /path/on/host/themes:/var/www/html/themes \
+	%%REPO%%
+```
+
+Another solution using Docker Volumes:
+
+```console
+$ docker volume create %%REPO%%-sites
+$ docker run --rm -v %%REPO%%-sites:/temporary/sites %%REPO%% cp -aRT /var/www/html/sites /temporary/sites
+$ docker run --name some-%%REPO%% --link some-postgres:postgres -d \
+	-v %%REPO%%-modules:/var/www/html/modules \
+	-v %%REPO%%-profiles:/var/www/html/profiles \
+	-v %%REPO%%-sites:/var/www/html/sites \
+	-v %%REPO%%-themes:/var/www/html/themes \
+```
+
 ## %%COMPOSE%%
 
 ## Adding additional libraries / extensions
diff --git a/drupal/docker-compose.yml b/drupal/docker-compose.yml
index 639716b3c..44bb30869 100644
--- a/drupal/docker-compose.yml
+++ b/drupal/docker-compose.yml
@@ -1,6 +1,7 @@
 # Drupal with PostgreSQL
 #
-# Access via "http://localhost:8080" (or "http://$(docker-machine ip):8080" if using docker-machine)
+# Access via "http://localhost:8080"
+#   (or "http://$(docker-machine ip):8080" if using docker-machine)
 #
 # During initial Drupal setup,
 # Database type: PostgreSQL
@@ -17,6 +18,14 @@ services:
     image: drupal:8.2-apache
     ports:
       - 8080:80
+    volumes:
+      - /var/www/html/modules
+      - /var/www/html/profiles
+      - /var/www/html/themes
+      # this takes advantage of the feature in Docker that a new anonymous
+      # volume (which is what we're creating here) will be initialized with the
+      # existing content of the image at the same location
+      - /var/www/html/sites
     restart: always
 
   postgres: