OpenStack Liberty Installation Guide: Debian¶

Problem description¶

The following steps need to be taken before the OpenStack Installation Guide for Debian can be re-published:

• Conversion to RST
• Testing and revision of content

Proposed change¶

1. Because of the similarity between Debian and Ubuntu, most Debian users can follow the Ubuntu installation instruction. Most Debian-specific configuration content is expected to be maintained in the Debconf chapter.

   Note

   The debconf system is the general interface between Debian and its user. It is used to change configuration directives of OpenStack services. However, we understand that the goal is not to just teach how to install OpenStack, but also to understand what should be configured in which directive of what section of what file. Therefore, the Debconf chapter will include explanations of the directives that the Debian packages handle automatically.

   To ensure that Debian users get the same level of understanding as other users, the Debconf chapter will document the following elements:

   • Debconf prompts
   • The directive influenced by the prompt
   • Screenshots showing the configuration results
   • Note that this information can be used for pre-seeding and puppet scripts as well.

2. Convert the Debconf chapter of Installation Guide to RST. This chapter describes the following procedures:

   • Setting up databases
   • RabbitMQ credentials (login, pass, host)
   • [keystone_authtoken] (login, pass, tenant and host)
   • API endpoints

   Note

   These need to be in a single chapter, to avoid repeating the same content for each service.

3. Convert Install and Configure section for each component to include references to the Debconf chapter as an alternative way to configure packages.

4. Use a debian tag to specify the conditional for Debian content according to the main specification: http://specs.openstack.org/openstack/docs-specs/specs/liberty/installguide-liberty-rst.html You can find added tags here: https://review.openstack.org/#/c/191516.

5. While RST migration will be going on, test the guide and report bugs on launchpad.

6. Prepare the drafts to fix the bugs.

7. Once migration is done, review the fixes.

8. Once updated, raise a discussion to publish the Debian Installation Guide on docs.openstack.org.

Implementation¶

Dependencies¶

The main dependency is on the main installation guide conversion described in http://specs.openstack.org/openstack/docs-specs/specs/liberty/installguide-liberty-rst.html.

Testing¶

The same procedures as specified in http://specs.openstack.org/openstack/docs-specs/specs/liberty/installguide-liberty-rst.html.

References¶

The plan and status of the Debian Installation Guide conversion will be tracked in the Etherpad

Discussion can occur using any official medium including IRC in #openstack-doc, the openstack-docs mailing list with [install-guide][debian] tags in the subject, weekly Installation Guide specialty team meeting, weekly documentation team meeting, and potentially etherpads.

In addition, Debian Installation Guide meetings can be arranged on Mondays at 13.00 UTC in Google Hangout to discuss the blocking issues.