ReadTheDocs in Docker

A Docker container for ReadTheDocs (RTD) which works and with many goodies.

Features

Optional database backend
Optional Redis cache support
Optional ElasticSearch support
Painless subdomain serving (i.e. {project}.docs.domain.com)
Correctly handles alternative domain names for projects
Want more? Open an issue or submit a pull request!

Installation

Compose

This is a preferred method. It will build and run the whole stack seamlessly.

Create an environment file based on the default one and point compose to it:

$ export ENV_NAME=my-org
$ cp {example,$ENV_NAME}.env && echo "RTD_ENV_FILE=$ENV_NAME.env" > .env

Adjust to your desired configuration (in $ENV_NAME.env file), then start:

$ docker-compose up

Standalone

Simply launch a docker run with relevant params.

$ docker run \
    -e RTD_PRODUCTION_DOMAIN=docs.example.com \
    -e RTD_USE_SUBDOMAIN=false \
    -e RTD_ALLOW_PRIVATE_REPOS=true \
    -p 80:80 \
    -d \
    readthedocs

Configurations / Environments

You can configure RTD's comportment with a bunch of environment variables described below.

Read the docs environment

All the RTD environment are prefixed with RTD_

Name	Description	Default value	RTD `config.py` target (if any)
`RTD_DEBUG`	Start RTD in debug mode	`'false'`	`DEBUG`
`RTD_ALLOW_PRIVATE_REPOS`	Configure RTD to let you use private repository (with credential inside the url)	`'false'`	`ALLOW_PRIVATE_REPOS`
`RTD_ACCOUNT_EMAIL_VERIFICATION`	If none turn off email verification	`'none'`	`ACCOUNT_EMAIL_VERIFICATION`
`RTD_PRODUCTION_DOMAIN`	The production domain use for nginx and RTD to configure the urls	`'localhost:8000'`	`PRODUCTION_DOMAIN`
`RTD_PUBLIC_DOMAIN`	The public domain of the application	Value of `RTD_PRODUCTION_DOMAIN`	`PUBLIC DOMAIN`
`RTD_USE_SUBDOMAIN`	Disable the `/docs/<project>` RTD routes and use only the subdomain	`'false'`	`USE_SUBDOMAIN`
`RTD_GLOBAL_ANALYTICS_CODE`	Your analytics code	`''`	`GLOBAL_ANALYTICS_CODE`

`RTD_ADMIN_USERNAME`	The username of the superuser account to create	`'admin'`	-
`RTD_ADMIN_PASSWORD`	The password of the superuser account to create	`'admin'`	-
`RTD_ADMIN_EMAIL`	The email address of the superuser account to create	`'{RTD_ADMIN_USERNAME}@{PRODUCTION_DOMAIN}`	-
`RTD_SLUMBER_USERNAME`	The username of the Slumber API account to create	`'slumber'`	`SLUMBER_USERNAME`
`RTD_SLUMBER_PASSWORD`	The password of the Slumber API account to create	`'slumber'`	`SLUMBER_PASSWORD`
`RTD_SLUMBER_EMAIL`	The email address of the Slumber API account to create	`'{RTD_SLUMBER_USERNAME}@localhost`	-
`RTD_SLUMBER_API_HOST`	Configure the host of the RTD slumber api	`'http://localhost:8000'`	`SLUMBER_API_HOST`

`RTD_HAS_DATABASE`	Configure Django with a database if `'true'` (see below)	`'false'`	-
`RTD_HAS_ELASTICSEARCH`	Configure the app with an ElasticSearch endpoint if `'true'` (see below)	`'false'`	-
`RTD_USE_REDIS_FOR_CACHE`	Configure the app with a Redis endpoint if `'true'` (see below)	`'false'`	-

To enable a postgre database, an elasticsearch server or a redis (as a cache) you will need to configure this following environment variable to true: RTD_HAS_DATABASE, RTD_HAS_ELASTICSEARCH, RTD_USE_REDIS_FOR_CACHE.

RTD components topology

When using docker-compose, defaults for these settings are used - they match across component configurations. You can change some of these setting via environment file.

If you're not using docker-compose, feel free to set these directly for the readthedocs container if you wish to connect to some backend.

Database (if `$RTD_HAS_DATABASE == 'true'`)

Name	Description	Default value	RTD `config.py` target (if any)
`DB_ENGINE`	Django DB engine	`'django.db.backends.postgresql_psycopg2'`	`DATABASES['default']['ENGINE']`
`DB_NAME`	DB name	`'readthedocs'`	`DATABASES['default']['NAME']`
`DB_USER`	DB user	`'rtd'`	`DATABASES['default']['USER']`
`DB_PASS`	DB password	`'rtd'`	`DATABASES['default']['PASSWORD']`
`DB_HOST`	DB host	`'database'`	`DATABASES['default']['HOST']`
`DB_PORT`	DB port	`5432`	`DATABASES['default']['PORT']`

These settings are ignored if the env var RTD_HAS_DATABASE is not set to 'true'.

ElasticSearch (if `$RTD_HAS_ELASTICSEARCH == 'true'`)

Name	Description	Default value	RTD `config.py` target (if any)
`ELASTICSEARCH_HOST`	Elasticsearch host	`'elasticsearch'`	`ES_HOSTS[0]` (as `{host}:{port}`)
`ELASTICSEARCH_PORT`	Elasticsearch port	`'9200'`	`ES_HOSTS[0]` (as `{host}:{port}`)

These settings are ignored if the env var RTD_HAS_ELASTICSEARCH is not set to 'true'.

Redis

Redis is used as Celery broker and is therefore mandatory. You can enable/disable Redis usage as a cache via RTD_USE_REDIS_FOR_CACHE env var.

Name	Description	Default value	RTD `config.py` target (if any)
`REDIS_HOST`	Redis host	`'redis'`	`REDIS['host']`
`REDIS_PORT`	Redis port	`'6379'`	`REDIS['port']`
`REDIS_DB`	Redis database	`'0'`	`REDIS['db']`

Credits to moul/docker-readthedocs

Credits to vassilvk/readthedocs-docker

maldag/docker-readthedocs