Add S3 photo storage backend

2 files changed, 192 insertions, 7 deletions

diff --git a/docs/customising/config.md b/docs/customising/config.md
index 9f48bad7e..e0761cb8e 100644
--- a/docs/customising/config.md
+++ b/docs/customising/config.md
@@ -55,10 +55,23 @@ The following are all the configuration settings that you can change in `conf/ge
 
 * <code><a href="#base_url">BASE_URL</a></code>
 * <code><a href="#secure_proxy_ssl_header">SECURE_PROXY_SSL_HEADER</a></code>
-* <code><a href="#upload_dir">UPLOAD_DIR</a></code>
 * <code><a href="#geo_cache">GEO_CACHE</a></code>
 * <code><a href="#admin_base_url">ADMIN_BASE_URL</a></code>
 
+### Photo storage
+
+* <code><a href="#photo_storage_backend">PHOTO_STORAGE_BACKEND</a></code>
+* <code><a href="#photo_storage_options">PHOTO_STORAGE_OPTIONS</a></code>
+  * For local filesystem storage:
+    * <code><a href="#upload_dir">UPLOAD_DIR</a></code>
+  * For Amazon S3 storage:
+    * <code><a href="#bucket">BUCKET</a></code>
+    * <code><a href="#access_key">ACCESS_KEY</a></code>
+    * <code><a href="#secret_key">SECRET_KEY</a></code>
+    * <code><a href="#prefix">PREFIX</a></code>
+    * <code><a href="#create_bucket">CREATE_BUCKET</a></code>
+    * <code><a href="#region">REGION</a></code>
+
 ### Emailing
 
 * <code><a href="#email_domain">EMAIL_DOMAIN</a></code>
@@ -404,18 +417,16 @@ LANGUAGES:
   </dd>
 
   <dt>
-    <a name="upload_dir"><code>UPLOAD_DIR</code></a> &amp;
     <a name="geo_cache"><code>GEO_CACHE</code></a>
   </dt>
   <dd>
-    The file locations for uploaded photos and cached geocoding results.
-    Normally you don't need to change these settings from the examples.
+    The file location for cached geocoding results.
+    Normally you don't need to change this setting from the example.
     <div class="more-info">
       <p>Example:</p>
       <ul class="examples">
         <li>
           <code>
-            UPLOAD_DIR: '../upload/'<br>
             GEO_CACHE: '../cache/'
           </code>
         </li>
@@ -1118,5 +1129,179 @@ ALLOWED_COBRANDS:
       </ul>
     </div>
   </dd>
-    
+
+  <dt>
+    <a name="photo_storage_backend"><code>PHOTO_STORAGE_BACKEND</code></a>
+  </dt>
+  <dd>
+    The storage backend to use for uploaded photos.
+    <p>
+      Possible choices are <code>FileSystem</code> or <code>S3</code>.
+      By default, FixMyStreet will use <code>FileSystem</code>.
+    </p>
+    <p>
+      The chosen backend can be configured via the
+      <code><a href="#photo_storage_options">PHOTO_STORAGE_OPTIONS</a></code>
+      setting, see below.
+    </p>
+  </dd>
+
+  <dt>
+    <a name="photo_storage_options"><code>PHOTO_STORAGE_OPTIONS</code></a>
+  </dt>
+  <dd>
+    <p>
+      Contains backend-specific configuration options for photo storage.
+    </p>
+    <p>
+      For the <code>FileSystem</code> backend, the following apply:
+    </p>
+    <ul>
+      <li><code><a href="#upload_dir">UPLOAD_DIR</a></code></li>
+    </ul>
+    <p>
+      For the <code>S3</code> backend, the following apply:
+    </p>
+    <ul>
+      <li><code><a href="#bucket">BUCKET</a></code></li>
+      <li><code><a href="#access_key">ACCESS_KEY</a></code></li>
+      <li><code><a href="#secret_key">SECRET_KEY</a></code></li>
+      <li><code><a href="#prefix">PREFIX</a></code></li>
+      <li><code><a href="#create_bucket">CREATE_BUCKET</a></code></li>
+      <li><code><a href="#region">REGION</a></code></li>
+    </ul>
+  </dd>
+
+  <dt>
+    <a name="upload_dir"><code>UPLOAD_DIR</code></a>
+  </dt>
+  <dd>
+    <p>
+      The file location for uploaded photos.
+      Normally you don't need to change this setting from the example.
+    </p>
+    <p>
+      Only applies when <code>PHOTO_STORAGE_BACKEND</code> is <code>FileSystem</code>.
+    </p>
+    <div class="more-info">
+      <p>Example:</p>
+      <ul class="examples">
+        <li>
+          <pre>
+PHOTO_STORAGE_OPTIONS:
+  UPLOAD_DIR: '../upload/'
+          </pre>
+        </li>
+      </ul>
+    </div>
+  </dd>
+
+  <dt>
+    <a name="bucket"><code>BUCKET</code></a>
+  </dt>
+  <dd>
+    <p>
+      The name of the S3 bucket to store photos in.
+    </p>
+    <p>
+      <strong>Required</strong> when <code>PHOTO_STORAGE_BACKEND</code> is <code>S3</code>.
+    </p>
+    <div class="more-info">
+      <p>Example:</p>
+      <ul class="examples">
+        <li>
+          <pre>
+PHOTO_STORAGE_OPTIONS:
+  BUCKET: 'fixmystreet-photos'
+          </pre>
+        </li>
+      </ul>
+    </div>
+  </dd>
+
+  <dt>
+    <a name="access_key"><code>ACCESS_KEY</code></a> &amp;
+    <a name="secret_key"><code>SECRET_KEY</code></a>
+  </dt>
+  <dd>
+    <p>
+      The AWS access & secret keys to use when connecting to S3.
+      You should use a role with minimal privileges to manage objects in a specific S3 bucket, not your root keys.
+    </p>
+    <p>
+      <strong>Required</strong> when <code>PHOTO_STORAGE_BACKEND</code> is <code>S3</code>.
+    </p>
+    <div class="more-info">
+      <p>Example:</p>
+      <ul class="examples">
+        <li>
+          <pre>
+PHOTO_STORAGE_OPTIONS:
+  ACCESS_KEY: 'AKIAMYSUPERCOOLKEY'
+  SECRET_KEY: '12345/AbCdEFgHIJ98765'
+          </pre>
+        </li>
+      </ul>
+    </div>
+  </dd>
+
+  <dt>
+    <a name="prefix"><code>PREFIX</code></a>
+  </dt>
+  <dd>
+    <p>
+      An optional directory prefix to prepended to S3 filenames. Useful if, for example, you are using a bucket shared between other projects or FixMyStreet instances.
+    </p>
+    <p>
+      <strong>Optional</strong>. Only applies when <code>PHOTO_STORAGE_BACKEND</code> is <code>S3</code>.
+    </p>
+    <div class="more-info">
+      <p>Example:</p>
+      <ul class="examples">
+        <li>
+          <pre>
+PHOTO_STORAGE_OPTIONS:
+  PREFIX: '/fixmystreet_photos/'
+          </pre>
+        </li>
+      </ul>
+    </div>
+  </dd>
+
+  <dt>
+    <a name="create_bucket"><code>CREATE_BUCKET</code></a>
+  </dt>
+  <dd>
+    <p>
+      Set to <code>1</code> (or <code>true</code>) if FixMyStreet should create the S3 bucket specified in <code>BUCKET</code> if it doesn't already exist.
+    </p>
+    <p>
+      <strong>Optional</strong>. Only applies when <code>PHOTO_STORAGE_BACKEND</code> is <code>S3</code>.
+    </p>
+  </dd>
+
+  <dt>
+    <a name="region"><code>REGION</code></a>
+  </dt>
+  <dd>
+    <p>
+      The AWS region to create the S3 bucket in.
+    </p>
+    <p>
+      <strong>Optional</strong>. Only applies when <code>CREATE_BUCKET</code> is enabled.
+    </p>
+    <div class="more-info">
+      <p>Example:</p>
+      <ul class="examples">
+        <li>
+          <pre>
+PHOTO_STORAGE_OPTIONS:
+  CREATE_BUCKET: 1
+  REGION: 'eu-west-2'
+          </pre>
+        </li>
+      </ul>
+    </div>
+  </dd>
+
 </dl>
diff --git a/docs/install/manual-install.md b/docs/install/manual-install.md
index 8acccdddf..84594f660 100644
--- a/docs/install/manual-install.md
+++ b/docs/install/manual-install.md
@@ -165,7 +165,7 @@ Some others you might want to look at, though the defaults are enough for it to
 * [CONTACT_EMAIL]({{ "/customising/config/#contact_email" | relative_url }}) -- the email address to be used on the site for the contact us form.
 * [DO_NOT_REPLY_EMAIL]({{ "/customising/config/#do_not_reply_email" | relative_url }}) -- the email address to be used on the site for e.g. confirmation emails.
 * [STAGING_SITE]({{ "/customising/config/#staging_site" | relative_url }}) -- if this is 1 then all email (alerts and reports) will be sent to the contact email address. Use this for development sites.
-* [UPLOAD_DIR]({{ "/customising/config/#upload_dir" | relative_url }}) -- this is the location where images will be stored when they are uploaded. It should be accessible by and writeable by the FixMyStreet process.
+* [PHOTO_STORAGE_OPTIONS.UPLOAD_DIR]({{ "/customising/config/#upload_dir" | relative_url }}) -- this is the location where images will be stored when they are uploaded. It should be accessible by and writeable by the FixMyStreet process.
 * [GEO_CACHE]({{ "/customising/config/#geo_cache" | relative_url }}) -- this is the location where Geolocation data will be cached. It should be accessible by and writeable by the FixMyStreet process.
 
 If you are using Bing or Google maps you should also set one of