diff --git a/README.rst b/README.rst index 9bda3d97b3..382ddb2c7b 100644 --- a/README.rst +++ b/README.rst @@ -8,83 +8,26 @@ from reusable components. The ``openstack_dashboard`` module is a reference implementation of a Django site that uses the ``horizon`` app to provide web-based interactions with the various OpenStack projects. -For release management: - - * https://launchpad.net/horizon - -For blueprints and feature specifications: - - * https://blueprints.launchpad.net/horizon - -For issue tracking: - - * https://bugs.launchpad.net/horizon +* Release management: https://launchpad.net/horizon +* Blueprints and feature specifications: https://blueprints.launchpad.net/horizon +* Issue tracking: https://bugs.launchpad.net/horizon -Getting Started -=============== +Using Horizon +============= -For local development, first create a virtualenv for the project. -In the ``tools`` directory there is a script to create one for you:: +See ``doc/source/topics/install.rst`` about how to install Horizon +in your OpenStack setup. It describes the example steps and +has pointers for more detailed settings and configurations. - $ python tools/install_venv.py +It is also available at http://docs.openstack.org/developer/horizon/topics/install.html. -Alternatively, the ``run_tests.sh`` script will also install the environment -for you and then run the full test suite to verify everything is installed -and functioning correctly. +Getting Started for Developers +============================== -Now that the virtualenv is created, you need to configure your local -environment. To do this, create a ``local_settings.py`` file in the -``openstack_dashboard/local/`` directory. There is a -``local_settings.py.example`` file there that may be used as a template. - -If all is well you should able to run the development server locally:: - - $ tools/with_venv.sh ./manage.py runserver - -or, as a shortcut:: - - $ ./run_tests.sh --runserver - - -Setting Up OpenStack -==================== - -The recommended tool for installing and configuring the core OpenStack -components is `Devstack`_. Refer to their documentation for getting -Nova, Keystone, Glance, etc. up and running. - -.. _Devstack: http://devstack.org/ - -.. note:: - - The minimum required set of OpenStack services running includes the - following: - - * Nova (compute, api, scheduler, network, *and* volume services) - * Glance - * Keystone - - Optional support is provided for Swift. - - -Development -=========== - -For development, start with the getting started instructions above. -Once you have a working virtualenv and all the necessary packages, read on. - -If dependencies are added to either ``horizon`` or ``openstack_dashboard``, -they should be added to ``requirements.txt``. - -The ``run_tests.sh`` script invokes tests and analyses on both of these -components in its process, and it is what Jenkins uses to verify the -stability of the project. If run before an environment is set up, it will -ask if you wish to install one. - -To run the unit tests:: - - $ ./run_tests.sh +``doc/source/quickstart.rst`` or +http://docs.openstack.org/developer/horizon/quickstart.html +describes how to setup Horizon development environment and start development. Building Contributor Documentation ================================== diff --git a/doc/source/index.rst b/doc/source/index.rst index 536173bb8a..a55a7acbd0 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -30,17 +30,15 @@ For a more in-depth look at Horizon and its architecture, see the To learn what you need to know to get going, see the :doc:`quickstart`. -Getting Started With Horizon -============================ +Using Horizon +============= How to use Horizon in your own projects. .. toctree:: :maxdepth: 1 - intro - quickstart - topics/tutorial + topics/install topics/deployment topics/settings topics/customizing @@ -60,6 +58,9 @@ Brief guides to areas of interest and importance when developing Horizon. .. toctree:: :maxdepth: 1 + intro + quickstart + topics/tutorial contributing testing diff --git a/doc/source/intro.rst b/doc/source/intro.rst index a546ce9911..2b5481c8dd 100644 --- a/doc/source/intro.rst +++ b/doc/source/intro.rst @@ -1,9 +1,6 @@ -=================== -Introducing Horizon -=================== - -.. contents:: Contents: - :local: +============== +Horizon Basics +============== Values ====== diff --git a/doc/source/quickstart.rst b/doc/source/quickstart.rst index 92c8e6dc3a..674fd03796 100644 --- a/doc/source/quickstart.rst +++ b/doc/source/quickstart.rst @@ -1,6 +1,6 @@ -================== -Horizon Quickstart -================== +========== +Quickstart +========== .. Note :: @@ -88,8 +88,12 @@ or to the IP and port the server is listening for. * Nova (compute, api, scheduler, and network) * Glance * Keystone + * Neutron (unless nova-network is used) - Optional support is provided for Swift. + Horizon provides optional support for other services. + See :ref:`system-requirements-label` for the supported services. + If Keystone endpoint for a service is configured, Horizon detects it + and enables its support automatically. Editing Horizon's Source diff --git a/doc/source/topics/install.rst b/doc/source/topics/install.rst new file mode 100644 index 0000000000..13466f259b --- /dev/null +++ b/doc/source/topics/install.rst @@ -0,0 +1,86 @@ +================== +Installing Horizon +================== + +This page covers the basic installation of Horizon. + +.. _system-requirements-label: + +System Requirements +=================== + +* Python 2.7 (or 2.6) +* Django 1.6 (1.4 and 1.5 are supported too) +* Minimum required set of running OpenStack services are: + + * Nova + * Keystone + * Glance + * Neutron (unless nova-network is used) + +* All other services are optional. + Horizon supports the following services in Juno release. + If Keystone endpoint for a service is configured, + Horizon detects it and enables its support automatically. + + * Swift + * Cinder + * Heat + * Ceilometer + * Trove + * Sahara + +Installation +============ + +1. Compile translation message catalogs for internationalization. + This step is not required if you do not need to support languages + other than English. GNU ``gettext`` tool is required to compile + message catalogs:: + + $ sudo apt-get install gettext + $ ./run_tests.sh --compilemessages + + This command compiles translation message catalogs within Python + virtualenv named ``.venv``. After this step, you can remove + ``.venv`` directory safely. + +2. Install Horizon python module into your system. Run the following + in the top directory.:: + + $ sudo pip install . + +3. Create ``openstack_dashboard/local/local_settings.py``. + It is usually a good idea to copy + ``openstack_dashboard/local/local_settings.py.example`` and edit it. + At least we need to customize the following variables in this file. + + * ``ALLOWED_HOSTS`` (unless ``DEBUG`` is ``True``) + * ``OPENSTACK_KEYSTONE_URL`` + + For more details, please refer to :doc:`deployment` and :doc:`settings`. + +4. Set up a web server with WSGI support. + It is optional but recommended in production deployments. + For example, install Apache web server on Ubuntu:: + + $ sudo apt-get install apache2 libapache2-mod-wsgi + + Then configure the web server to host OpenStack Dashboard via WSGI. + For apache2 web server, you may need to create + ``/etc/apache2/site-available/horizon.conf``. + The template in devstack is a good example of the file. + http://git.openstack.org/cgit/openstack-dev/devstack/tree/files/apache-horizon.template + +5. Finally, enable the above configuration and restart the web server.:: + + $ sudo a2ensite horizon + $ sudo service apache2 restart + +Next Steps +========== + +* :doc:`deployment` covers some common questions, concerns and pitfalls you + may encounter when deploying Horizon in a production environment. +* :doc:`settings` lists the available settings for Horizon. +* :doc:`customizing` describes how to customizing Horizon as you want. diff --git a/doc/source/topics/settings.rst b/doc/source/topics/settings.rst index 7a2aad4956..b501c21e99 100644 --- a/doc/source/topics/settings.rst +++ b/doc/source/topics/settings.rst @@ -1,6 +1,6 @@ -================================== -Horizon Settings and Configuration -================================== +========================== +Settings and Configuration +========================== Introduction ============ diff --git a/doc/source/topics/tutorial.rst b/doc/source/topics/tutorial.rst index b9340373c3..d6033060e2 100644 --- a/doc/source/topics/tutorial.rst +++ b/doc/source/topics/tutorial.rst @@ -1,6 +1,6 @@ -=================== -Building on Horizon -=================== +============================================ +Tutorial: Building a Dashboard using Horizon +============================================ This tutorial covers how to use the various components in Horizon to build an example dashboard and a panel with a tab which has a table containing data