Public | Automated Build

Last pushed: 2 years ago
Short Description
ReadTheDocs in docker
Full Description

ReadTheDocs in Docker

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

Features

  • Optional database backend
  • Optional Redis+Celery support
  • Optional ElasticSearch support (untested)
  • 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

Standalone

Simply launch a docker run with relevant params.

$ docker run \
    -e RTD_PRODUCTION_DOMAIN=example.com \
    -e RTD_USE_SUBDOMAIN=true \
    -e RTD_ALLOW_PRIVATE_REPOS=true \
    -p 8000:80 \
    -d \
    floross/docker-readthedocs

Compose

Create a compose file:

$ cp docker-compose.yml{.example,}

Adjust to your desired configuration, then start:

$ docker-compose up

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}@localhost -
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_HAS_REDIS Configure the app with a Redis endpoint if 'true' (see below) 'false' -

To enable a postgre database, an elasticsearch server or a redis you will need to configure this following environment variable to true: RTD_HAS_DATABASE, RTD_HAS_ELASTICSEARCH, RTD_HAS_REDIS

Database (if $RTD_HAS_DATABASE == 'true')

These vars are automatically assigned by docker-compose from the env vars of
the db container (i.e. db's DB_NAME env var is accessible by
readthedocs as DB_ENV_DB_NAME). If you're not using docker-compose, feel
free to set these directly for the readthedocs container if you wish to
connect to a database.

Name Description Default value RTD config.py target (if any)
DB_ENV_ENGINE Django DB engine 'django.db.backends.postgresql_psycopg2' DATABASES['default']['ENGINE']
DB_ENV_DB_NAME DB name 'readthedocs' DATABASES['default']['NAME']
DB_ENV_DB_USER DB user 'root' DATABASES['default']['USER']
DB_ENV_DB_PASS DB password None DATABASES['default']['PASSWORD']
DB_ENV_HOST DB host 'localhost' DATABASES['default']['HOST']
DB_ENV_PORT DB port 5432 DATABASES['default']['PORT']

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

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

These vars are automatically assigned by docker-compose from the env vars of
the elasticsearch container (i.e. elasticsearch's HOST env var is
accessible by readthedocs as ELASTICSEARCH_ENV_HOST). If you're not using
docker-compose, feel free to set these directly for the readthedocs
container if you wish to use elasticsearch.

Name Description Default value RTD config.py target (if any)
ELASTICSEARCH_ENV_HOST Elasticsearch host 'localhost' ES_HOSTS[0] (as {host}:{port})
ELASTICSEARCH_ENV_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 (if $RTD_HAS_REDIS == 'true')

These vars are automatically assigned by docker-compose from the env vars of
the redis container (i.e. redis's HOST env var is accessible by
readthedocs as REDIS_ENV_HOST). If you're not using docker-compose, feel
free to set these directly for the readthedocs container if you wish to use
redis.

Using Redis will start a celery worker on readthedocs to handle build tasks.

Name Description Default value RTD config.py target (if any)
REDIS_ENV_HOST Redis host 'localhost' REDIS['host']
REDIS_ENV_PORT Redis port '6379' REDIS['port']
REDIS_ENV_DB Redis database '0' REDIS['db']

Enabling Redis will start a celery worker on readthedocs to handle build
tasks. It will also set the following flags on config.py:

  • BROKER_URL is set to 'redis://{host}:{port}/{db}' ;
  • CELERY_RESULT_BACKEND is set to 'redis://{host}:{port}/{db}' ;
  • CELERY_ALWAYS_EAGER is set to False.

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


Credits to moul/docker-readthedocs

Credits to vassilvk/readthedocs-docker

Docker Pull Command
Owner
floross
Source Repository

Comments (0)