Docker image to run readthedocs.org on-premise.
The recommended approach is to use docker-compose. It contains full stack necessary to
run readthedocs.org app including PostgresSQL database, nginx reverse proxy, celery workers,
Redis and the application itself. The project setup is meant to be run with docker-compose - standalone
run is discouraged.
Simply run docker-compose up, and application will start.
For configuration, suggested approach is to use docker-compose.override.yml file. An example file content is shown below:
version: '3'
services:
web:
environment:
- RTD_ADMIN_USERNAME=rtd-admin
- RTD_ADMIN_EMAIL=rtd-admin@example.com
- RTD_DOMAIN=<your-readthedocs-domain>
nginx:
ports:
- 80:8000
The admin account is created only on first startup when database is empty and RTD_ADMIN_USERNAME
environment variable is set. The password is autogenerated, it will appear only once in the log.
Look for a following message in web application logs:
Created admin account with username: "rtd-admin" and password: "<random-pass>". Save the password somewhere, as it won't appear again.
Save the password, or change it because as the message says - it won't appear again.
If you run via docker-compose, in the workdir will be created the .data directory.
This directory is necessary to preserve database and build images in case if the containers
will be removed.
WARNING! As mentioned the official elasticsearch docs,
you may need to set vm.max_map_count in kernel to at least 262144 in order to run ElasticSearch.
The docker-compose.yaml comes with sane defaults allowing you to quickly test the solution,
but before deploying into production, you may need to do some setup.
All the configuration is done via environment variables:
- RTD_DOMAIN (
localhost): domain name of the readthedocs instance, - RTD_ADMIN_USERNAME (
rtd-admin) - username for the admin user; this is set in the compose file, no admin account will be created if this variable is missing, - RTD_ADMIN_EMAIL (
rtd-admin@example.com) - readthedocs admin e-mail, - RTD_DEBUG (
False): run Django in debug mode, - RTD_DB_NAME (
rtd): name of the Postgres readthedocs database, - RTD_DB_USER (
rtd-user): username for the database, - RTD_DB_PASS (
rtd-password): database password, - RTD_DB_HOST (
db): hostname with running database, - RTD_SLUMBER_USER (
slumber): username for the slumber API; the account will be created if missing, - RTD_SLUMBER_PASS (
<slumber-password>): password for slumber API; the slumber account is a superuser account, so you should keep the password secret, - RTD_REDIS_HOST (
redis): hostname with running Redis, - RTD_REDIS_PORT (
6379): port number to connect with Redis, - RTD_ELASTIC_HOST (
elasticsearch): hostname of the Elasticsearch server, - RTD_ELASTIC_PORT (
9200): port number for Elasticsearch.