diff --git a/contrib/Dockerfile b/contrib/Dockerfile new file mode 100644 index 00000000000..216a4414bcc --- /dev/null +++ b/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"] diff --git a/contrib/docker_build.sh b/contrib/docker_build.sh new file mode 100755 index 00000000000..a0dde12d63f --- /dev/null +++ b/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} diff --git a/contrib/readme.rst b/contrib/readme.rst index dfa46ae0e6d..ccc3a6a898c 100644 --- a/contrib/readme.rst +++ b/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 diff --git a/docs/development/buildenvironments.rst b/docs/development/buildenvironments.rst index a6804680ffb..b47c309736f 100644 --- a/docs/development/buildenvironments.rst +++ b/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``. diff --git a/readthedocs/settings/dev.py b/readthedocs/settings/dev.py index 48c6e13ae36..48933f753a3 100644 --- a/readthedocs/settings/dev.py +++ b/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