Quickstart¶

Linux Systems¶

Install the prerequisite packages.

On Ubuntu

$ sudo apt-get install git python-pip

On RPM-based distributions (e.g., Fedora/RHEL/CentOS/Scientific Linux)

$ sudo yum install gcc git-core python-devel python-virtualenv openssl-devel libffi-devel which

Setup¶

To begin setting up a Horizon development environment simply clone the Horizon git repository from https://git.openstack.org/cgit/openstack/horizon

$ git clone https://git.openstack.org/openstack/horizon

Next you will need to configure Horizon by adding a local_settings.py file. A good starting point is to use the example config with the following command, from within the horizon directory.

$ cp openstack_dashboard/local/local_settings.py.example openstack_dashboard/local/local_settings.py

Horizon connects to the rest of OpenStack via a Keystone service catalog. By default Horizon looks for an endpoint at http://localhost:5000/v2.0; this can be customised by modifying the OPENSTACK_HOST and OPENSTACK_KEYSTONE_URL values in openstack_dashboard/local/local_settings.py

Horizon uses tox to manage virtual environments for testing and other development tasks. You can install it with

$ pip install tox

The tox environments provide wrappers around manage.py. For more information on manage.py, which is a Django command, see https://docs.djangoproject.com/en/dev/ref/django-admin/

To start the Horizon development server use the command below

$ tox -e runserver

Once the Horizon server is running, point a web browser to http://localhost or to the IP and port the server is listening for. Enter your Keystone credentials, log in and you’ll be presented with the Horizon dashboard. Congratulations!

Managing Settings¶

You can save changes you made to openstack_dashboard/local/local_settings.py with the following command:

$ python manage.py migrate_settings --gendiff

If you upgrade Horizon, you might need to update your openstack_dashboard/local/local_settings.py file with new parameters from openstack_dashboard/local/local_settings.py.example to do so, first update Horizon

$ git remote update && git pull --ff-only origin master

Then update your openstack_dashboard/local/local_settings.py file

$ mv openstack_dashboard/local/local_settings.py openstack_dashboard/local/local_settings.py.old
$ python manage.py migrate_settings

When all settings have been migrated, it is safe to regenerate a clean diff in order to prevent Conflicts for future migrations

$ mv openstack_dashboard/local/local_settings.diff openstack_dashboard/local/local_settings.diff.old
$ python manage.py migrate_settings --gendiff

Editing Horizon’s Source¶

Although DevStack installs and configures an instance of Horizon when running stack.sh, the preferred development setup follows the instructions above on the server/VM running DevStack. There are several advantages to maintaining a separate copy of the Horizon repo, rather than editing the DevStack installed copy.

• Source code changes aren’t as easily lost when running unstack.sh / stack.sh
• The development server picks up source code changes while still running.
• Log messages and print statements go directly to the console.
• Debugging with pdb becomes much simpler to interact with.

Horizon’s Structure¶

This project is a bit different from other OpenStack projects in that it has two very distinct components underneath it: horizon, and openstack_dashboard.

The horizon directory holds the generic libraries and components that can be used in any Django project.

The openstack_dashboard directory contains a reference Django project that uses horizon.

For development, both pieces share an environment which (by default) is built with the tools/install_venv.py script. That script creates a virtualenv and installs all the necessary packages.

If dependencies are added to either horizon or openstack_dashboard, they should be added to requirements.txt.

Project Structure¶

url(r'', include(horizon.urls)),

{% load horizon %}

<div class='nav'>
  {% horizon_main_nav %}
</div>

{% load horizon %}

<div class='sidebar'>
  {% horizon_dashboard_nav %}
</div>

Application Design¶

project/
|---__init__.py
|---dashboard.py <-----Registers the app with Horizon and sets dashboard properties
|---overview/
|---images/
    |-- images
    |-- __init__.py
    |---panel.py <-----Registers the panel in the app and defines panel properties
    |-- snapshots/
    |-- templates/
    |-- tests.py
    |-- urls.py
    |-- views.py
    ...
...

import horizon

....
# ObjectStorePanels is an example for a PanelGroup
# for panel classes in general, see below
class ObjectStorePanels(horizon.PanelGroup):
    slug = "object_store"
    name = _("Object Store")
    panels = ('containers',)


class Project(horizon.Dashboard):
    name = _("Project") # Appears in navigation
    slug = "project"    # Appears in URL
    # panels may be strings or refer to classes, such as
    # ObjectStorePanels
    panels = (BasePanels, NetworkPanels, ObjectStorePanels)
    default_panel = 'overview'
    ...

horizon.register(Project)

import horizon

from openstack_dashboard.dashboards.project import dashboard


class Images(horizon.Panel):
    name = "Images"
    slug = 'images'
    permissions = ('openstack.roles.admin', 'my.openstack.permission',)
    policy_rules = (('endpoint', 'endpoint:rule'),)

# You could also register your panel with another application's dashboard
dashboard.Project.register(Images)