rearrange existing documentation to follow the new layout

Change-Id: I50774641757af1a608ebf739a7f171725bd4f9ec
This commit is contained in:
Ilya Etingof 2017-07-17 13:06:03 +02:00
parent 6eb00df34c
commit 094276cda7
13 changed files with 212 additions and 228 deletions

View File

@ -3,185 +3,7 @@ MoltenIron overview
MoltenIron maintains a pool of bare metal nodes.
Installation
------------
With a clean installation of an Ubuntu 16.04 system, do the following::
$ sudo apt-get install -y build-essential python-dev python3-dev
$ sudo apt-get install -y libmysqlclient-dev tox python2.7 python3.5
$ sudo apt-get install -y mysql-server
If you see::
E: Unable to locate package tox
then remove tox and reinstall. Next, do the following::
$ sudo pip install --upgrade tox
Then, check out the MoltenIron project::
$ git clone git://git.openstack.org/openstack/molteniron.git
$ cd molteniron/
Before you can install the package requirements, you may need to install a
prerequisite (on a non-clean system)::
$ hash mysql_config || sudo apt install -y libmysqlclient-dev
Then install the package requirements::
$ sudo pip install -U --force-reinstall -r requirements.txt
Before starting the server for the first time, the createDB.py
script must be run as follows::
$ createDB.py
Or with a clean installation of an Ubuntu 16.04 system, do the following::
$ sudo apt-get update
$ git clone git://git.openstack.org/openstack/molteniron.git
$ cd molteniron/
$ ./utils/install_requirements.sh
You can run the suite of testcases to make sure everything works::
$ (rm -rf .tox/py27/ testenv/; tox -epy27)
$ (rm -rf .tox/py35/ testenv/; tox -epy35)
Starting
--------
To start the server::
$ sudo moltenirond-helper start
To stop the server::
$sudo moltenirond-helper stop
MoltenIron client
-----------------
Use the molteniron client (molteniron) to communicate with the server. For
usage information type::
$ molteniron -h
For usage of a specific command use::
$ molteniron [command] -h
MoltenIron commands
-------------------
+----------+---------------------------------------------+
|command | description |
+==========+=============================================+
|add | Add a node |
+----------+---------------------------------------------+
|allocate | Allocate a node |
+----------+---------------------------------------------+
|release | Release a node |
+----------+---------------------------------------------+
|get_field | Get a specific field in a node |
+----------+---------------------------------------------+
|set_field | Set a specific field with a value in a node |
+----------+---------------------------------------------+
|status | Return the status of every node |
+----------+---------------------------------------------+
|delete_db | Delete every database entry |
+----------+---------------------------------------------+
Configuration of MoltenIron
---------------------------
Configuration of MoltenIron is specified in the file conf.yaml.
"Both" means that this configuration option is required for both the client and
the server. "Client" means that it is required only for the client. "Server"
means it is only required for the server.
+-------+------------+----------------------------------------------------------+
|usage | key | description |
+=======+============+==========================================================+
|Both | mi_port | the port that the server uses to respond to commands. |
+-------+------------+----------------------------------------------------------+
|Client | serverIP | The IP address of the server. This is only used by |
| | | clients. |
+-------+------------+----------------------------------------------------------+
|Server | maxTime | The maximum amount of time, in seconds, that a node |
| | | is allowed to be allocated to a particular BM node. |
+-------+------------+----------------------------------------------------------+
|Server | logdir | The path to the directory where the logs should be |
| | | stored. |
+-------+------------+----------------------------------------------------------+
|Server | maxLogDays | The amount of time, in days, to keep old logs. |
+-------+------------+----------------------------------------------------------+
|Server | sqlUser | The username to use for the MI server. This user |
| | | will automatically be generated when createDB.py is run. |
+-------+------------+----------------------------------------------------------+
|Server | sqlPass | The password of sqlUser |
+-------+------------+----------------------------------------------------------+
Running testcases
-----------------
The suite of testcases is checked by tox. But, before you can run tox, you
need to change the local yaml configuration file to point to the log
directory. An example::
(LOG=$(pwd)/testenv/log; sed -i -r -e 's,^(logdir: )(.*)$,\1'${LOG}',' conf.yaml; rm -rf testenv/; tox -e testenv)
Running inside a Continuous Integration environment
---------------------------------------------------
During the creation of a job, in the pre_test_hook.sh, add the following snippet of bash code::
# Setup MoltenIron and all necessary prerequisites.
# And then call the MI script to allocate a node.
(
REPO_DIR=/opt/stack/new/molteniron
MI_CONF_DIR=/usr/local/etc/molteniron
MI_IP=10.1.2.3 # @TODO - Replace with your IP addr here!
# Grab molteniron and install it
git clone https://git.openstack.org/openstack/molteniron ${REPO_DIR} || exit 1
cd ${REPO_DIR}
# @BUG Install prerequisite before running pip to install the requisites
hash mysql_config || sudo apt install -y libmysqlclient-dev
# Install the requisites for this package
sudo pip install --upgrade --force-reinstall --requirement requirements.txt
# Run the python package installation program
sudo python setup.py install
if [ -n "${MI_IP}" ]
then
# Set the molteniron server IP in the conf file
sudo sed -i "s/127.0.0.1/${MI_IP}/g" ${MI_CONF_DIR}/conf.yaml
fi
sudo ${REPO_DIR}/utils/test_hook_mi_ipmiblob.py \
--hardware-info=/opt/stack/new/devstack/files/hardware_info \
--localrc=/opt/stack/new/devstack/localrc \
${dsvm_uuid} \
1
) || exit $?
and change the MI_IP environment variable to be your MoltenIron server!
During the destruction of a job, in the post_test_hook.sh, add the following snippet of bash code::
DSVM_UUID="$(</etc/nodepool/uuid)"
echo "Cleaning up resources associated with node: ${DSVM_UUID}"
molteniron release ${DSVM_UUID}
* Free software: Apache license
* Documentation: https://docs.openstack.org/molteniron/
* Source: http://git.openstack.org/cgit/openstack/molteniron
* Bugs: http://bugs.launchpad.net/molteniron

View File

@ -23,7 +23,7 @@ sys.path.insert(0, os.path.abspath('../..'))
extensions = [
'sphinx.ext.autodoc',
#'sphinx.ext.intersphinx',
'oslosphinx'
'openstackdocstheme',
]
# autodoc generation is a bit aggressive and a nuisance when doing heavy
@ -37,7 +37,7 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = u'molteniron.git'
project = u'Molten Iron'
copyright = u'2016, OpenStack Foundation'
# If true, '()' will be appended to :func: etc. cross-reference text.
@ -57,6 +57,7 @@ pygments_style = 'sphinx'
# html_theme_path = ["."]
# html_theme = '_theme'
# html_static_path = ['static']
html_theme = 'openstackdocs'
# Output file base name for HTML help builder.
htmlhelp_basename = '%sdoc' % project

View File

@ -1,4 +1,4 @@
============
Contributing
============
.. include:: ../../CONTRIBUTING.rst
.. include:: ../../../CONTRIBUTING.rst

View File

@ -3,23 +3,17 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to molteniron.git's documentation!
========================================================
Welcome to Molten Iron's documentation!
=======================================
MoltenIron maintains a pool of bare metal nodes.
Contents:
.. toctree::
:maxdepth: 2
readme
installation
usage
contributing
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
:maxdepth: 1
install/index
user/index
reference/index
contributor/index

View File

@ -0,0 +1,48 @@
Installation
============
With a clean installation of an Ubuntu 16.04 system, do the following::
$ sudo apt-get install -y build-essential python-dev python3-dev
$ sudo apt-get install -y libmysqlclient-dev tox python2.7 python3.5
$ sudo apt-get install -y mysql-server
If you see::
E: Unable to locate package tox
then remove tox and reinstall. Next, do the following::
$ sudo pip install --upgrade tox
Then, check out the MoltenIron project::
$ git clone git://git.openstack.org/openstack/molteniron.git
$ cd molteniron/
Before you can install the package requirements, you may need to install a
prerequisite (on a non-clean system)::
$ hash mysql_config || sudo apt install -y libmysqlclient-dev
Then install the package requirements::
$ sudo pip install -U --force-reinstall -r requirements.txt
Before starting the server for the first time, the createDB.py
script must be run as follows::
$ createDB.py
Or with a clean installation of an Ubuntu 16.04 system, do the following::
$ sudo apt-get update
$ git clone git://git.openstack.org/openstack/molteniron.git
$ cd molteniron/
$ ./utils/install_requirements.sh
You can run the suite of testcases to make sure everything works::
$ (rm -rf .tox/py27/ testenv/; tox -epy27)
$ (rm -rf .tox/py35/ testenv/; tox -epy35)

View File

@ -1,12 +0,0 @@
============
Installation
============
At the command line::
$ pip install molteniron.git
Or, if you have virtualenvwrapper installed::
$ mkvirtualenv molteniron.git
$ pip install molteniron.git

View File

@ -1 +0,0 @@
.. include:: ../../README.rst

View File

@ -4,15 +4,14 @@
http://creativecommons.org/licenses/by/3.0/legalcode
===========
Molten Iron
===========
https://bugs.launchpad.net/ironic/+bug/1633540
======================
Molten Iron motivation
======================
Running Ironic on a set of Bare Metal machines needs a database and library
to help manage the pool.
See also Launchpad bug `#1633540 <https://bugs.launchpad.net/ironic/+bug/1633540>`_.
Problem description
===================

View File

@ -1,7 +0,0 @@
========
Usage
========
To use molteniron.git in a project::
import molteniron

139
doc/source/user/index.rst Normal file
View File

@ -0,0 +1,139 @@
Usage
=====
Starting
--------
To start the server::
$ sudo moltenirond-helper start
To stop the server::
$sudo moltenirond-helper stop
MoltenIron client
-----------------
Use the molteniron client (molteniron) to communicate with the server. For
usage information type::
$ molteniron -h
For usage of a specific command use::
$ molteniron [command] -h
MoltenIron commands
-------------------
+----------+---------------------------------------------+
|command | description |
+==========+=============================================+
|add | Add a node |
+----------+---------------------------------------------+
|allocate | Allocate a node |
+----------+---------------------------------------------+
|release | Release a node |
+----------+---------------------------------------------+
|get_field | Get a specific field in a node |
+----------+---------------------------------------------+
|set_field | Set a specific field with a value in a node |
+----------+---------------------------------------------+
|status | Return the status of every node |
+----------+---------------------------------------------+
|delete_db | Delete every database entry |
+----------+---------------------------------------------+
Configuration of MoltenIron
---------------------------
Configuration of MoltenIron is specified in the file conf.yaml.
"Both" means that this configuration option is required for both the client and
the server. "Client" means that it is required only for the client. "Server"
means it is only required for the server.
+-------+------------+----------------------------------------------------------+
|usage | key | description |
+=======+============+==========================================================+
|Both | mi_port | the port that the server uses to respond to commands. |
+-------+------------+----------------------------------------------------------+
|Client | serverIP | The IP address of the server. This is only used by |
| | | clients. |
+-------+------------+----------------------------------------------------------+
|Server | maxTime | The maximum amount of time, in seconds, that a node |
| | | is allowed to be allocated to a particular BM node. |
+-------+------------+----------------------------------------------------------+
|Server | logdir | The path to the directory where the logs should be |
| | | stored. |
+-------+------------+----------------------------------------------------------+
|Server | maxLogDays | The amount of time, in days, to keep old logs. |
+-------+------------+----------------------------------------------------------+
|Server | sqlUser | The username to use for the MI server. This user |
| | | will automatically be generated when createDB.py is run. |
+-------+------------+----------------------------------------------------------+
|Server | sqlPass | The password of sqlUser |
+-------+------------+----------------------------------------------------------+
Running testcases
-----------------
The suite of testcases is checked by tox. But, before you can run tox, you
need to change the local yaml configuration file to point to the log
directory. An example::
(LOG=$(pwd)/testenv/log; sed -i -r -e 's,^(logdir: )(.*)$,\1'${LOG}',' conf.yaml; rm -rf testenv/; tox -e testenv)
Running inside a Continuous Integration environment
---------------------------------------------------
During the creation of a job, in the pre_test_hook.sh, add the following snippet of bash code::
# Setup MoltenIron and all necessary prerequisites.
# And then call the MI script to allocate a node.
(
REPO_DIR=/opt/stack/new/molteniron
MI_CONF_DIR=/usr/local/etc/molteniron
MI_IP=10.1.2.3 # @TODO - Replace with your IP addr here!
# Grab molteniron and install it
git clone https://git.openstack.org/openstack/molteniron ${REPO_DIR} || exit 1
cd ${REPO_DIR}
# @BUG Install prerequisite before running pip to install the requisites
hash mysql_config || sudo apt install -y libmysqlclient-dev
# Install the requisites for this package
sudo pip install --upgrade --force-reinstall --requirement requirements.txt
# Run the python package installation program
sudo python setup.py install
if [ -n "${MI_IP}" ]
then
# Set the molteniron server IP in the conf file
sudo sed -i "s/127.0.0.1/${MI_IP}/g" ${MI_CONF_DIR}/conf.yaml
fi
sudo ${REPO_DIR}/utils/test_hook_mi_ipmiblob.py \
--hardware-info=/opt/stack/new/devstack/files/hardware_info \
--localrc=/opt/stack/new/devstack/localrc \
${dsvm_uuid} \
1
) || exit $?
and change the MI_IP environment variable to be your MoltenIron server!
During the destruction of a job, in the post_test_hook.sh, add the following snippet of bash code::
DSVM_UUID="$(</etc/nodepool/uuid)"
echo "Cleaning up resources associated with node: ${DSVM_UUID}"
molteniron release ${DSVM_UUID}

View File

@ -38,7 +38,7 @@
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'oslosphinx',
'openstackdocstheme',
'reno.sphinxext',
]
@ -111,7 +111,7 @@ pygments_style = 'sphinx'
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
html_theme = 'openstackdocs'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the

View File

@ -27,6 +27,7 @@ packages =
source-dir = doc/source
build-dir = doc/build
all_files = 1
warning-is-error = 1
[upload_sphinx]
upload-dir = doc/build/html

View File

@ -7,7 +7,7 @@ hacking>=0.11.0,<0.12 # Apache-2.0
coverage>=4.0 # Apache-2.0
python-subunit>=0.0.18 # Apache-2.0/BSD
sphinx>=1.2.1,!=1.3b1,<1.4 # BSD
oslosphinx>=4.7.0 # Apache-2.0
openstackdocstheme>=1.11.0 # Apache-2.0
oslotest>=1.10.0 # Apache-2.0
testrepository>=0.0.18 # Apache-2.0/BSD
testscenarios>=0.4 # Apache-2.0/BSD