We’re moving to Read The Docs

Project Discussions
, , , , ,
2

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. We also added an Sphinx extension for redirects 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 or the pre-collections redirects.

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 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 will still be available from the legacy-controller-docs.ansible.com subdomain.
  • Provide entry points to the main pages that will be available after the migration, as follows:
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:

    • Create a new legacy-controller-docs directory with correct permissions.
    • Set correct ownership and permissions for the jenkins user on the docs and legacy-controller-docs directories.

  2. Configure the web server to handle requests for legacy-controller-docs.ansible.com by adding a new VirtualHost such as:

<VirtualHost *:80>
    ServerName legacy-controller-docs.ansible.com
    DocumentRoot /var/www/html/legacy-controller-docs/
    Options +Indexes
    <Directory /var/www/html/legacy-controller-docs/>
                Options Indexes FollowSymLinks MultiViews
                AllowOverride FileInfo Options=MultiViews
                Order allow,deny
                allow from all
    </Directory>
</VirtualHost>

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 the archive subdomain and docs.ansible.com.
  2. Determine if legacy-controller-docs.ansible.com has an A record, for example: dig a legacy-controller-docs.ansible.com
  3. Determine if docs.ansible.com has a CNAME record, for example: dig cname docs.ansible.com
  4. Verify TTL for docs.ansible.com, for example: dig docs.ansible.com +ttlunits

We can also complete the following steps to test that everything is set up correctly:

  1. Ensure that the archive landing page is available from legacy-controller-docs.ansible.com.
  2. Ensure that entry points for legacy Automation Controller documentation is available from legacy-controller-docs.ansible.com.
  3. Ensure that the docsite build job in Jenkins can update the archive landing page.
  4. Ensure that both legacy-controller-docs.ansible.com and docs.ansible.com serve the same set of web pages, for example: gobuster dns -d docs.ansible.com -w /path/to/wordlist.txt.

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.

5 Likes