Installation Guides

Pike and later

Each official OpenStack project should maintain an installation guide following the layout described in Project guide setup. When the guide is available, update openstack-manuals/www/project-data/latest.yaml to include information about the project and ensure that the has_install_guide flag is set to true to ensure that the guide is listed along with the guides from other projects.

Newton and Ocata

For the Newton and Ocata releases only, big tent projects created their own installation guides, based on a standard template, in their own repository. These guides were then centrally published to


The following instructions are superseded by Project guide setup. New installation guides should be created using the layout defined in the spec, rather than the following instructions.

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

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





    The name of the install guide directory inside the project repository. This should be, install-guide.



    The service name what the project implements.

    Compute, Telemetry Alarming, or Root Cause Analysis


    The name how the different components of the project are referring 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:

    whitelist_externals = rm
    commands =
            rm -rf install-guide/build
            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
  2. In jenkins/jobs/projects.yaml, add install-guide-jobs within the entry for your project:

    - project:
        name: heat
         - 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
        - name: install-guide-jobs

    This schedules the Install Guide jobs.

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