Add a contrib Dockerfile for local build image on Linux

contrib/Dockerfile

@@ -0,0 +1,16 @@
+ARG label
+
+FROM readthedocs/build:${label}
+
+ARG uid
+ARG gid
+
+ENV UID ${uid}
+ENV GID ${gid}
+
+USER root
+RUN groupmod --gid ${GID} docs
+RUN usermod --uid ${UID} --gid ${GID} docs
+USER docs
+
+CMD ["/bin/bash"]

contrib/docker_build.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+
+uid=`id -u`
+gid=`id -g`
+basedir=`dirname "$0"`
+dockerfile=${basedir}/Dockerfile
+
+version=$1
+[ -n "${version}" ] || version="latest"
+
+docker build \
+    --no-cache \
+    -t readthedocs/build-dev:${version} \
+    --build-arg uid=${uid} \
+    --build-arg gid=${gid} \
+    --build-arg label=${version} \
+    - <${dockerfile}

contrib/readme.rst

@@ -1,5 +1,16 @@
+Contrib
+=======
+
+Building development Docker image
+---------------------------------
+
+If you run Linux, you likely need to build a local Docker image that extends our
+default image::
+
+    contrib/docker_build.sh latest
+
 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,29 @@ 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 the UID and GID for the
+normal container user::
+
+    contrib/docker_build.sh latest
+
+This will create a new image, ``readthedocs/build-dev:latest``. To build a
+different image, you can instead specify a version to build::
+
+    contrib/docker_build.sh 5.0
+
+This will create a new image, ``readthedocs/build-dev:5.0``.
+
+You can set a ``local_settings.py`` option to automatically patch the image
+names to the development image names that are built here:
+
+DOCKER_USE_DEV_IMAGES
+    If set to ``True``, replace the normal Docker image name used in building
+    ``readthedocs/build`` with the image name output for these commands,
+    ``readthedocs/build-dev``.

readthedocs/settings/dev.py

@@ -83,3 +83,14 @@ def MIDDLEWARE(self):
         from .local_settings import *  # noqa
     except ImportError:
         pass
+
+# Allow for local settings override to trigger images name change
+try:
+    if DOCKER_USE_DEV_IMAGES:
+        DOCKER_IMAGE_SETTINGS = {
+            key.replace('readthedocs/build:', 'readthedocs/build-dev:'): settings
+            for (key, settings)
+            in DOCKER_IMAGE_SETTINGS.items()
+        }
+except NameError:
+    pass