Skip to content

Latest commit

 

History

History
127 lines (90 loc) · 6.58 KB

README.md

File metadata and controls

127 lines (90 loc) · 6.58 KB
Raw

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