144 lines
4.1 KiB
ReStructuredText
144 lines
4.1 KiB
ReStructuredText
.. _project-install-guide:
|
|
|
|
===================
|
|
Installation Guides
|
|
===================
|
|
|
|
Pike and later
|
|
~~~~~~~~~~~~~~
|
|
|
|
Each official OpenStack project should maintain an installation guide
|
|
following the layout described in :doc:`project-guides`. 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
|
|
`docs.openstack.org <https://docs.openstack.org>`_.
|
|
|
|
.. warning::
|
|
|
|
The following instructions are superseded by :doc:`project-guides`. New
|
|
installation guides should be created using the layout defined in the spec,
|
|
rather than the following instructions.
|
|
|
|
Set up project specific installation guides:
|
|
|
|
#. Install ``cookiecutter``:
|
|
|
|
.. code-block:: console
|
|
|
|
# pip install cookiecutter
|
|
|
|
#. 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:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cookiecutter https://opendev.org/openstack/installguide-cookiecutter.git
|
|
|
|
You will be prompted to answer the following questions to complete the
|
|
installation:
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - 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 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.
|
|
|
|
#. Create a ``tox.ini`` environment for ``install-guide`` in your project
|
|
repository, using this content:
|
|
|
|
.. code-block:: ini
|
|
|
|
[testenv:install-guide]
|
|
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
|
|
|
|
#. Add the python package ``openstackdocstheme`` to the
|
|
``test-requirements.txt`` file. Copy the exact requirement line from the
|
|
`global file
|
|
<https://opendev.org/openstack/requirements/src/branch/master/global-requirements.txt>`_:
|
|
|
|
.. code-block:: none
|
|
|
|
openstackdocstheme>=1.5.0 # Apache-2.0
|
|
|
|
#. Add your installation content, and test the build locally with ``tox``:
|
|
|
|
.. code-block:: console
|
|
|
|
$ tox -e install-guide
|
|
|
|
The local build will be generated in the ``install-guide/build/html``
|
|
directory".
|
|
|
|
#. Commit the changes to your project repository for review.
|
|
|
|
|
|
After these changes have merged, you can set up the jobs for building.
|
|
|
|
#. Clone the ``project-config`` repo:
|
|
|
|
.. code-block:: console
|
|
|
|
$ git clone https://opendev.org/openstack/project-config
|
|
|
|
#. In ``jenkins/jobs/projects.yaml``, add ``install-guide-jobs`` within the
|
|
entry for your project:
|
|
|
|
.. code-block:: yaml
|
|
|
|
- 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.
|
|
|
|
#. In ``zuul/layout.yaml``, locate the entry for your project and add the
|
|
``install-guide-jobs`` template:
|
|
|
|
.. code-block:: yaml
|
|
|
|
- name: openstack/heat
|
|
template:
|
|
- name: install-guide-jobs
|
|
|
|
This schedules the Install Guide jobs.
|
|
|
|
#. Commit the changes to the infra repository for review.
|