DCD-639: Add section to README about overriding the provided templates.

README.md

@@ -11,6 +11,10 @@ Learn more about Confluence Server: <https://www.atlassian.com/software/confluen
 
 You can find the repository for this Dockerfile at <https://hub.docker.com/r/atlassian/confluence-server>
 
+# Contents
+
+[TOC]
+
 # Overview
 
 This Docker container makes it easy to get an instance of Confluence up and
@@ -28,7 +32,7 @@ configured with `CONFLUENCE_SHARED_HOME`.
 
 Start Atlassian Confluence Server:
 
-    $> docker run -v /data/your-confluence-home:/var/atlassian/application-data/confluence --name="confluence" -d -p 8090:8090 -p 8091:8091 atlassian/confluence-server
+    docker run -v /data/your-confluence-home:/var/atlassian/application-data/confluence --name="confluence" -d -p 8090:8090 -p 8091:8091 atlassian/confluence-server
 
 
 **Success**. Confluence is now available on <http://localhost:8090>*
@@ -37,9 +41,19 @@ Please ensure your container has the necessary resources allocated to it.  We
 recommend 2GiB of memory allocated to accommodate the application server.  See
 [Supported Platforms][4] for further information.
 
- 
 _* Note: If you are using `docker-machine` on Mac OS X, please use `open http://$(docker-machine ip default):8090` instead._
 
+# Configuring Confluence
+
+This Docker image is intended to be configured from its environment; the
+provided information is used to generate the application configuration files
+from templates. This allows containers to be repeatably created and destroyed
+on-the-fly, as required in advanced cluster configurations. Most aspects of the
+deployment can be configured in this manner; the necessary environment variables
+are documented below. However, if your particular deployment scenario is not
+covered by these settings, it is possible to override the provided templates
+with your own; see the section _Advanced Configuration_ below.
+
 ## Memory / Heap Size
 
 If you need to override Confluence Server's default memory allocation, you can
@@ -228,6 +242,43 @@ management technology, and is beyond the scope of this documentation.
 
    The multicast address the cluster will communicate on.
 
+## Advanced Configuration
+
+As mentioned at the top of this section, the settings from the environment are
+used to populate the application configuration on the container startup. However
+in some cases you may wish to customise the settings in ways that are not
+supported by the environment variables above. In this case, it is possible to
+modify the base templates to add your own configuration. There are three main
+ways of doing this; modify our repository to your own image, build a new image
+from the existing one, or provide new templates at startup. We will briefly
+outline this methods here, but practice how you do this will depend on your
+needs.
+
+#### Building your own image
+
+* Clone the Atlassian repository at https://bitbucket.org/atlassian-docker/docker-atlassian-confluence-server/
+* Modify or replace the [Jinja](https://jinja.palletsprojects.com/) templates
+  under `config`; _NOTE_: The files must have the `.j2` extensions. However you
+  don't have to use template variables if you don't wish.
+* Build the new image with e.g: `docker build --tag my-confluence-image --build-arg CONFLUENCE_VERSION=6.x.x .`
+* Optionally push to a registry, and deploy.
+
+#### Build a new image from the existing one
+
+* Create a new `Dockerfile`, which starts with the line e.g: `FROM atlassian/confluence-server:latest`.
+* Use a `COPY` line to overwrite the provided templates.
+* Build, push and deploy the new image as above.
+
+#### Overwrite the templates at runtime
+
+There are two main ways of doing this:
+
+* If your container is going to be long-lived, you can create it, modify the
+  installed templates under `/opt/atlassian/etc/`, and then run it.
+* Alternatively, you can create a volume containing your alternative templates,
+  and mount it over the provided templates at runtime
+  with `--volume my-config:/opt/atlassian/etc/`.
+
 # Shared directory and user IDs
 
 By default the Confuence application runs as the user `confluence`, with a UID
@@ -244,9 +295,9 @@ of options available:
 To upgrade to a more recent version of Confluence Server you can simply stop the
 `Confluence` container and start a new one based on a more recent image:
 
-    $> docker stop confluence
+    docker stop confluence
-    $> docker rm confluence
+    docker rm confluence
-    $> docker run ... (see above)
+    docker run ... (see above)
 
 As your data is stored in the data volume directory on the host, it will still
 be available after the upgrade.