# We’re moving to Read The Docs **URL:** \ **Category:** Project Discussions\ **Tags:** community, mindshare, community-wg-nextmtg, documentation, ansible-lint\ **Created:** [June 23, 2025, 6:38pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519 "2025-06-23T18:38:11Z")\ **Posts on this page:** 1\ **Showing post:** 2
**Author:** ![oranod](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/oranod/32/1434_2.png) [@oranod](https://forum.ansible.com/u/oranod)\ **Post date:** [June 23, 2025, 6:47pm UTC](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519/2 "2025-06-23T18:47:58Z")
# Preparing for a successful migration Before we dive into the tasks involved in the migration plan, let’s go over some of the things we’ve been doing to get ready. ## Replacement subdomain for controller docs As mentioned a bit earlier, there is some Automation controller documentation available from `docs.ansible.com`. That documentation is intended for Red Hat customers and is not moving to Read The Docs. We plan to keep the content on the web server after the migration is complete. For this reason, we need to create a new subdomain so folks can still find Automation controller documentation. We’ve consulted the team responsible for that content and have decided to go with the `legacy-controller-docs.ansible.com` subdomain. ## Consolidating and converting redirects To facilitate the migration to Read The Docs, we had to drastically reduce the number of server-side redirects. Read The Docs imposes a limit of 100 redirects per project. When we started out with the documentation for the Ansible community package, there were thousands of server-side redirects. Earlier this year we [consolidated all the pre-collections redirects](https://forum.ansible.com/t/consolidating-redirects-on-docs-ansible-com/38897/). We also added an [Sphinx extension for redirects](https://github.com/ansible/ansible-documentation/pull/2418/) in the Ansible community docs. As a result, we should not break any redirects in place for the Ansible community docs defined in the [top-level .htaccess file](https://raw.githubusercontent.com/ansible/docsite/refs/heads/main/.htaccess) or the [pre-collections redirects](https://raw.githubusercontent.com/ansible/docsite/576d5a6ed12d566cc9c13904dc179155b1ef4bfa/ansible/11/.htaccess). # Phase one: Setting things up Phase one of the migration sets up the `legacy-controller-docs.ansible.com` subdomain for Automation controller docs and adjusts DNS records. ## Creating a separate landing page We need to create a landing page for the `legacy-controller-docs.ansible.com` subdomain that should: - Briefly explain the migration to Read The Docs. - Provide clear links to Ansible community and Ansible core documentation. - Notify that Ansible core documentation from version 2.15 and later will be available from [docs.ansible.com](http://docs.ansible.com) after the migration. Note that we can enable builds for earlier versions in Read The Docs if necessary. It would be good to get feedback. - Explain that we will not remove any pages from the current server but will no longer actively maintain or update them. For example, [Getting started with Ansible — Ansible Community Documentation](https://docs.ansible.com/ansible/11/getting_started/index.html) will still be available from the [legacy-controller-docs.ansible.com](http://legacy-controller-docs.ansible.com) subdomain. - Provide entry points to the main pages that will be available after the migration, as follows: ```auto ansible-tower.html automation-tower-chinese-translations.html automation-tower-japanese-translations.html automation-tower-korean-translations.html automation-tower-prior-versions.html platform.html ``` To create the archive landing page, do the following: 1. Create an `archive-index.html` in the `ansible/docsite` repository. This index page should be as simple as possible and not generated from any template. It should use straightforward inline styling. 2. Update the `.htaccess` configuration to allow access to `archive-index.html`. 3. Update the docsite build job in Jenkins to deploy `archive-index.html` to the web server. After migration, we will separate the index page from the `ansible/docsite` repository. ## Configuring DNS Create a new LB record for `legacy-controller-docs.ansible.com` that points to the two servers and uses the same configuration as `docs.ansible.com`. ## Configuring the web server We will serve `legacy-controller-docs` from the same server as `docs.ansible.com`. 1. Update the `roles/docs_and_release/tasks/main.yml` playbook to: 2. Configure the web server to handle requests for `legacy-controller-docs.ansible.com` by adding a new `VirtualHost` such as: ```auto ServerName legacy-controller-docs.ansible.com DocumentRoot /var/www/html/legacy-controller-docs/ Options +Indexes Options Indexes FollowSymLinks MultiViews AllowOverride FileInfo Options=MultiViews Order allow,deny allow from all ``` ## Setting things up on disc 1. Add a reference to the `ansible-tower` directory to the `index-archive.html` page. 2. Do a once off copy from `/var/www/html/docs/automation-controller ` AND `/var/www/html/docs/ansible-tower` to `/var/www/html/legacy-controller-docs`. 3. Move `/var/www/html/docs/index-archive.html` to `/var/www/html/legacy-controller-docs/index.html` 4. Copy landing pages into `/var/www/html/legacy-controller-docs`: - `platform.html` - `automation-tower-prior-versions.html` 1. Update controller jenkins jobs to rsync to the legacy-controller-docs folder instead of the docs folder. 2. Update the docsite jenkins job to remove the rsync for the `index-archive.html` file. ## Test plan for phase one The archive subdomain, `legacy-controller-docs.ansible.com`, will be served from Red Hat managed infrastructure. 1. Use dig to verify DNS settings for `legacy-controller-docs.ansible.com` and `docs.ansible.com`. 2. Ensure that the archive landing page is available from `legacy-controller-docs.ansible.com`. 3. Ensure that entry points for legacy Automation Controller documentation is available from `legacy-controller-docs.ansible.com`. 4. Ensure that the docsite build job in Jenkins can update the archive landing page. EDIT: I’ve updated plan details after working through a few changes. The original plan was based on more of a bottom up view that started from looking at what was on the server. After getting into some of the changes on cloudflare it made sense to take a slightly different approach and more cleanly separate things from the top-level down to disc. EDIT2: Removed some of the steps from the test plan that no longer apply. --- _[View the full topic](https://forum.ansible.com/t/we-re-moving-to-read-the-docs/43519)._