Add a contrib Dockerfile for local build image on Linux (#4608)

* 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

* Use always latest image to build the Docker image

* Make image label configurable in docker build script

This re-reverts back to using label for some of the dockerfile. Also,
instead of creating a group, we simply groupmod the existing docs group.

This doesn't address the configuration changes necessary for development
images yet.

* Update command call for docker_build.sh

* Add configuration option that patches the docker image names in development

This setting can be used from local_settings.py, and signifies that you
have run ``docker_build.sh`` to build local development images that
replace the UID/GID.

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