A Docker container for ReadTheDocs (RTD) which works and with many goodies.
- 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!
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
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
You can configure RTD's comportment with a bunch of environment variables described below.
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.
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.
| 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'.
| 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 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
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent