Add a contrib Dockerfile for local build image on Linux

This is necessary as permissions are all incorrect on the paths that are
shared between the host system and the Docker build container.

Closes #2692

Author: agjohnson

contrib/Dockerfile

@@ -0,0 +1,17 @@
+FROM readthedocs/build:4.0rc1
+
+ARG username
+ARG uid=1000
+ARG gid=$uid
+ARG label=latest
+
+ENV USERNAME ${username}
+ENV UID ${uid}
+ENV GID ${gid}
+
+USER root
+RUN groupadd --gid $GID $USERNAME
+RUN useradd -m --uid $UID --gid $GID $USERNAME
+USER $username
+
+CMD ["/bin/bash"]

contrib/docker_build.sh

@@ -0,0 +1,16 @@
+#!/bin/sh
+
+username=`id -nu`
+uid=`id -u`
+gid=`id -g`
+
+version=$1
+[ -n "${version}" ] || version="latest"
+
+docker build \
+    -t readthedocs/build:dev \
+    --build-arg username=${username} \
+    --build-arg uid=${uid} \
+    --build-arg gid=${gid} \
+    --build-arg label=${version} \
+    .

contrib/readme.rst

@@ -1,5 +1,17 @@
+Contrib
+=======
+
+Building development Docker image
+---------------------------------
+
+If you run Linux, you likely need to build a local Docker image that extends our
+default image::
+
+    cd contrib/
+    ./docker_build.sh
+
 Running Read the Docs via Supervisord
-=====================================
+-------------------------------------
 
 This is the easiest way to start all of the commands you'll need for development
 in an environment relatively close to the production evironment. All you need is

docs/development/buildenvironments.rst

@@ -82,3 +82,23 @@ DOCKER_VERSION
     Version of the API to use for the Docker API client.
 
     Default: :djangosetting:`DOCKER_VERSION`
+
+Local development
+-----------------
+
+On Linux development environments, it's likely that your UID and GID do not
+match the ``docs`` user that is set up as the default user for builds. In this
+case, it's necessary to make a new image that overrides this user::
+
+    cd contrib/
+    ./docker_build.sh
+
+You can also specify a specific image version to use::
+
+    cd contrib/
+    ./docker_build.sh 4.0rc1
+
+This will create a new image, ``readthedocs/build:dev``, which you can specify
+as the default image in local settings overrides::
+
+    DOCKER_IMAGE = 'readthedocs/build:dev'