diff options
| -rw-r--r-- | doc/source/dev/dev-quickstart.rst | 111 |
1 files changed, 107 insertions, 4 deletions
diff --git a/doc/source/dev/dev-quickstart.rst b/doc/source/dev/dev-quickstart.rst index 98d98560b..814ed42b3 100644 --- a/doc/source/dev/dev-quickstart.rst +++ b/doc/source/dev/dev-quickstart.rst @@ -5,7 +5,7 @@ Developer Quick-Start ===================== This is a quick walkthrough to get you started developing code for Ironic. -This assumes you are already familiar with submitting code reviews to +This assumes you are already familiar with submitting code reviews to an OpenStack project. .. seealso:: @@ -37,7 +37,10 @@ Setting up a local environment for development can be done with tox:: # activate the virtualenv source .tox/venv/bin/activate - # run testr init + # install requirements within the virtualenv + pip install -U -r requirements.txt test-requirements.txt + + # initialize testr testr init To run the pep8/flake8 syntax and style checks:: @@ -47,10 +50,110 @@ To run the pep8/flake8 syntax and style checks:: To run Ironic's unit test suite:: - # run unit tests + # run all the unit tests testr run -When you're done, to leave the venv:: + # to run specific tests only, specify the file, module or test name, eg: + testr run test_conductor + +When you're done:: # deactivate the virtualenv deactivate + +=============================== +Exercising the Services Locally +=============================== + +If you would like to exercise the Ironic services in isolation within a local +virtual environment, you can do this without starting any other OpenStack +services. For example, this is useful for rapidly prototyping and debugging +interactions over the RPC channel, testing database migrations, and so forth. + +First, install prerequisites:: + + # install rabbit message broker + # Ubuntu/Debian: + sudo apt-get install rabbitmq-server + + # Fedora/RHEL: + sudo yum install rabbitmq-server + + # install ironic CLI + sudo pip install python-ironicclient + +Then, activate the virtual environment created in the previous section, and run +everything else within that:: + + # enter the ironic directory + cd <your source dir> + cd ironic + + # activate the virtualenv + source .tox/venv/bin/activate + + # install ironic within the virtualenv + python setup.py develop + + # initialize the ironic database; this defaults to storing data in + # ./ironic/openstack/common/db/ironic.sqlite + ironic-dbsync + + # copy sample config and modify it as necessary + cp etc/ironic/ironic.conf.sample etc/ironic/ironic.conf.local + cat >> etc/ironic/ironic.conf.local <<EOL + host = test-host + auth_strategy = noauth + EOL + + # start services and observe their output + # for each service, open a separate window and active the virtualenv in it + ironic-api -v -d --config-file etc/ironic/ironic.conf.local + ironic-conductor -v -d --config-file etc/ironic/ironic.conf.local + + # export ENV vars so ironic client connects to the local services + export OS_AUTH_TOKEN=fake-token + export IRONIC_URL=http://localhost:6385/ + + # you should now be able to query the Ironic API + # and see a list of supported drivers on "test-host" + ironic driver-list + + # enroll nodes with the "fake" driver, eg: + ironic node-create -d fake + + # if you make some code changes and want to test their effects, + # install again with "python setup.py develop", stop the services + # with Ctrl-C, and restart them. + +================================ +Building developer documentation +================================ + +If you would like to build the documentation locally, eg. to test your +documentation changes before uploading them for review, you should install and +configure Apache to serve the output. Below are some basic instructions. This +guide does not cover the many ways one can configure Apache, nor does it +address security issues with running a web server on your laptop. +(In other words, you might want to do this in a VM.) + +:: + + # Install Apache on Ubuntu/Debian + sudo apt-get install apache2 + + # Install Apache on Fedora/RHEL + sudo yum install httpd + sudo systemctl start httpd + + # Add symlink to build output. For this example, let's assume your + # Apache DocumentRoot is /var/www and ironic source is at /opt/stack/ironic + cd /var/www + sudo ln -s /opt/stack/ironic/doc/build/html ironic + cd /opt/stack/ironic + + # build the documentation + source .tox/venv/bin/activate + python setup.py build_sphinx + + # open a web browser pointed to http://localhost/ironic/index.html |