Installation tutorials and guides¶

For the Newton release, a new method of publishing installation tutorials and guides is being implemented. This will allow each big tent project to create their own installation guide, based on a standard template, in their own repository. These guides are then centrally published to docs.openstack.org.

For updates on the progress of this project, see the Install Guide wiki page. If you would like to help out, attend a meeting.

Set up project specific installation guides:

1. Install cookiecutter:

   # pip install cookiecutter
   

2. Run the Install Guide cookiecutter in the top-level directory of your projects repository to create a skeleton for the install guide of your project:

   $ cookiecutter https://git.openstack.org/openstack/installguide-cookiecutter.git
   

   You will be prompted to answer the following questions to complete the installation:

   Parameter	Explanation	Example
   directory_name	The name of the install guide directory inside the project repository. This should be, install-guide.	install-guide
   service	The service name what the project implements.	Compute, Telemetry Alarming, or Root Cause Analysis
   codename	The name how the different components of the project are refering to the project	nova, aodh, or vitrage as in nova-conductor or vitrage-api

   A directory will be created with the name that was defined in directory_name (usually install-guide) with the skeleton of the install guide.

3. Create a tox.ini environment for install-guide in your project repository, using this content:

   [testenv:install-guide]
   commands = sphinx-build -a -E -W -d install-guide/build/doctrees -b html install-guide/source install-guide/build/html
   

4. Add the python package openstackdocstheme to the test-requirements.txt file. Copy the exact requirement line from the global file:

   openstackdocstheme>=1.5.0  # Apache-2.0
   

5. Add your installation content, and test the build locally with tox:

   $ tox -e install-guide
   

   The local build will be generated in the install-guide/build/html directory”.

6. Commit the changes to your project repository for review.

After these changes have merged, you can set up the jobs for building.

1. Clone the project-config repo:

   $ git clone https://git.openstack.org/openstack-infra/project-config
   

2. In jenkins/jobs/projects.yaml, add install-guide-jobs within the entry for your project:

   - project:
       name: heat
   
       jobs:
       ...
        - install-guide-jobs:
            service: orchestration
   

   Here service is the service name of the project, like orchestration for heat.

   This defines the jobs using the JJB install-guide-jobs job-template.

3. In zuul/layout.yaml, locate the entry for your project and add the install-guide-jobs template:

   - name: openstack/heat
     template:
       - name: install-guide-jobs
   

   This schedules the Install Guide jobs.

4. Commit the changes to the infra repository for review.

To create or update the master index file, create or update the www/project-install-guide/RELEASE/index.html file and the doc/install-guide/source/additional-services.rst at the openstack-manuals repository. For draft (unreleased) version, replace RELEASE with draft.