Read the Docs

Last reviewed Aug 26, 2026 · 801 words

You almost certainly should not self-host Read the Docs, and the project agrees. The code that runs readthedocs.org is MIT-licensed and public, which is why it lands in this directory with 8,378 stars and a "Hard" rating, but the maintainers state that they do not support self-hosted installations and that the Docker setup in the repository is for developing Read the Docs, not for running it. What follows is the case for ignoring that advice, the cost of doing so, and the route that gets 90 percent of the value for a fraction of the effort.

What "self-hostable" means here

Read the Docs is two products. The public service hosts open-source documentation for free with builds triggered by Git webhooks, versioned per branch and tag, translated per language, with full-text search. Read the Docs for Business is the paid tier with private repositories and single sign-on. The community edition source is what both run on, and it is a Django monolith that has grown since 2010 into a large platform: web app, Celery workers, PostgreSQL, Redis, Elasticsearch for search, nginx, object storage for built HTML, and a build system that launches Docker containers, which means the worker needs access to the Docker socket on its host.

That is eight moving parts before you have built a single page, and none of them is optional. The 2 GB memory floor is the number for a developer's laptop; a working instance building real projects wants 4 GB or more and a disk that grows with every version you keep.

When the pain is worth it

There is a genuine case, and it looks like this: a company with 30 or more repositories, each producing Sphinx or MkDocs output, that needs every branch and tag built automatically, pull-request previews, per-project access control, and a search box across all of it, all inside the corporate network where the hosted Business tier is not permitted. In that setting Read the Docs's versioning model, which treats each Git ref as a first-class documentation version with its own URL, is the thing no static-site pipeline gives you without building it yourself. If you have that problem and an engineer who can own a Django deployment, self-hosting is defensible.

If your list of requirements is shorter than that, it is not.

What running it actually involves

Expect to read the repository's Compose file and rewrite it. The development setup uses local settings modules, self-signed certificates and a build image that assumes it can pull from Docker Hub. You will replace object storage with MinIO or a mounted volume, put real PostgreSQL and Redis behind it, expose only nginx, and decide how builds get network access to your internal Git host. Upgrades are git pull and migrations, and because the project deploys continuously to its own service there are no versioned releases to pin to; you are tracking a moving main. Budget a day for the first install and an hour a month after that, and accept that no one will answer a support ticket.

The cheaper route for most teams

Most people who search for "self-host Read the Docs" want three things: docs built from Git automatically, versioned by release, and served from their own domain. That is a CI job and a web server.

MkDocs with the Material theme builds a site in seconds; the mike tool adds a version switcher by publishing each release into a branch. Docusaurus does the same with React and its own versioning built in. Either one, built in Gitea Actions or GitLab CI and copied to a directory that Caddy serves, replicates the visible result on 50 MB of RAM with no Elasticsearch. Search comes from the theme's client-side index, which is fine up to a few thousand pages. For non-Git content, where people want to edit in a browser, BookStack is the better shape entirely, and the Confluence alternatives page sets out that side.

And if the documentation is for an open-source project, the hosted readthedocs.org service is free, supported, and already does everything above.

What I'd do

For a company with dozens of Sphinx projects and a hard requirement to keep them on-premises, I would self-host, own it properly with a dedicated 4 GB VM and a written upgrade routine, and stop expecting upstream support. For everyone else I would build MkDocs Material in CI, publish versions with mike, and serve the result from Caddy. It is a 2-hour setup, it is maintained by the same tools your developers already use, and it will still be running when nobody remembers who set it up.