openstack/horizon
Code Issues Proposed changes

Update and merge the install / deployment docs

Browse Source 
These two documents were incredibly outdated, but also had almost
identical concerns. This patch updates the content and merges the two
documents.

Note that this guide is still separate to the quickstart guide, which is
intended for developers. In future patches in this blueprint, the file &
navigation structure will be altered to make this distinction more
clear.

Change-Id: Ic5d111d53ab69a3cd1ab08c4c05b2d676e79258c
Implements: blueprint pike-docs-overhaul
This commit is contained in:
Rob Cresswell 2017-06-13 17:21:09 +01:00
parent 53a16f6624
commit de5bc4b46b
12 changed files with 268 additions and 364 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
README.rst
View File

@ -18,11 +18,12 @@ web-based interactions with the various OpenStack projects.
Using Horizon Using Horizon
============= =============
See ``doc/source/topics/install.rst`` about how to install Horizon See ``doc/source/install/index.rst`` about how to install Horizon
in your OpenStack setup. It describes the example steps and in your OpenStack setup. It describes the example steps and
has pointers for more detailed settings and configurations. has pointers for more detailed settings and configurations.
It is also available at http://docs.openstack.org/developer/horizon/topics/install.html. It is also available at
http://docs.openstack.org/developer/horizon/install/index.html.
Getting Started for Developers Getting Started for Developers
============================== ==============================

11
doc/source/index.rst
View File

@ -36,14 +36,9 @@ Using Horizon
How to use Horizon in your own projects. How to use Horizon in your own projects.
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 2
topics/install install/index
topics/deployment
topics/settings
topics/customizing
topics/packaging
browser_support
Developer Docs Developer Docs
============== ==============
@ -59,7 +54,7 @@ the following documentation is provided.
quickstart quickstart
contributing contributing
testing testing
plugin_registry browser_support
tutorials/index tutorials/index
topics/index topics/index
ref/index ref/index

0
doc/source/topics/customizing.rst → doc/source/install/customizing.rst
View File

241
doc/source/install/deploy-guide.rst Normal file
View File

@ -0,0 +1,241 @@
================================
Installing and Deploying Horizon
================================
This page covers the basic installation of horizon in a production
environment. If you are looking for a developer enviroment, see
:doc:`Quickstart </quickstart>`.
.. _system-requirements-label:
System Requirements
===================
* Python 2.7
* Django 1.8
* An accessible `keystone <https://docs.openstack.org/developer/keystone>`_ endpoint
* All other services are optional.
Horizon supports the following services as of the Pike release.
If the keystone endpoint for a service is configured,
horizon detects it and enables its support automatically.
* `cinder <https://docs.openstack.org/developer/cinder>`_: Block Storage
* `glance <https://docs.openstack.org/developer/glance>`_: Image Management
* `heat <https://docs.openstack.org/developer/heat>`_: Orchestration
* `neutron <https://docs.openstack.org/developer/neutron>`_: Networking
* `nova <https://docs.openstack.org/developer/nova>`_: Compute
* `swift <https://docs.openstack.org/developer/swift>`_: Object Storage
* Horizon also supports many other OpenStack services via plugins. For more
information, see the :doc:`plugin-registry`.
Installation
============
.. note::
In the commands below, substitute "<release>" for your version of choice,
such as "ocata" or "pike".
#. Clone Horizon
.. code-block:: console
$ git clone https://git.openstack.org/openstack/horizon -b stable/<release> --depth=1
$ cd horizon
#. Install the horizon python module into your system
.. code-block:: console
$ sudo pip install -c http://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt?h=stable/<release> .
Configuration
=============
This section contains a small summary of the critical settings required to run
horizon. For more details, please refer to :doc:`settings`.
Settings
--------
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. As a minimum, the follow settings will need to be modified:
``DEBUG``
Set to ``False``
``ALLOWED_HOSTS``
Set to your domain name(s)
``OPENSTACK_HOST``
Set to the IP of your Keystone endpoint. You may also
need to alter ``OPENSTACK_KEYSTONE_URL``
.. note::
The following steps in the "Configuration" section are optional, but highly
recommended in production.
Translations
------------
Compile translation message catalogs for internationalization. This step is
not required if you do not need to support languages other than US English.
GNU ``gettext`` tool is required to compile message catalogs.
.. code-block:: console
$ sudo apt-get install gettext
$ ./manage.py compilemessages
Static Assets
-------------
Compress your static files by adding ``COMPRESS_OFFLINE = True`` to your
``local_settings.py``, then run the following commands
.. code-block:: console
$ ./manage.py collectstatic
$ ./manage.py compress
Logging
-------
Horizons uses Django's logging configuration mechanism, which can be customized
by altering the ``LOGGING`` dictionary in ``local_settings.py``. By default,
Horizon's logging example sets the log level to ``INFO``.
Horizon also uses a number of 3rd-party clients which log separately. The
log level for these can still be controlled through Horizon's ``LOGGING``
config, however behaviors may vary beyond Horizon's control.
For more information regarding configuring logging in Horizon, please
read the `Django logging directive`_ and the `Python logging directive`_
documentation. Horizon is built on Python and Django.
.. _Django logging directive: https://docs.djangoproject.com/en/dev/topics/logging
.. _Python logging directive: http://docs.python.org/2/library/logging.html
Session Storage
---------------
Horizon uses `Django's sessions framework`_ for handling session data. There
are numerous session backends available, which are selected through the
``SESSION_ENGINE`` setting in your ``local_settings.py`` file.
.. _Django's sessions framework: https://docs.djangoproject.com/en/dev/topics/http/sessions/
Memcached
~~~~~~~~~
.. code-block:: python
SESSION_ENGINE = 'django.contrib.sessions.backends.cache'
CACHES = {
'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache'
'LOCATION': 'my_memcached_host:11211',
}
External caching using an application such as memcached offers persistence
and shared storage, and can be very useful for small-scale deployment and/or
development. However, for distributed and high-availability scenarios
memcached has inherent problems which are beyond the scope of this
documentation.
Requirements:
* Memcached service running and accessible
* Python memcached module installed
Database
~~~~~~~~
.. code-block:: python
SESSION_ENGINE = 'django.core.cache.backends.db.DatabaseCache'
DATABASES = {
'default': {
# Database configuration here
}
}
Database-backed sessions are scalable (using an appropriate database strategy),
persistent, and can be made high-concurrency and highly-available.
The downside to this approach is that database-backed sessions are one of the
slower session storages, and incur a high overhead under heavy usage. Proper
configuration of your database deployment can also be a substantial
undertaking and is far beyond the scope of this documentation.
Cached Database
~~~~~~~~~~~~~~~
To mitigate the performance issues of database queries, you can also consider
using Django's ``cached_db`` session backend which utilizes both your database
and caching infrastructure to perform write-through caching and efficient
retrieval. You can enable this hybrid setting by configuring both your database
and cache as discussed above and then using
.. code-block:: python
SESSION_ENGINE = "django.contrib.sessions.backends.cached_db"
Deployment
==========
#. Set up a web server with WSGI support. For example, install Apache web
server on Ubuntu
.. code-block:: console
$ sudo apt-get install apache2 libapache2-mod-wsgi
You can either use the provided ``openstack_dashboard/wsgi/django.wsgi`` or
generate a ``openstack_dashboard/wsgi/horizon.wsgi`` file with the following
command (which detects if you use a virtual environment or not to
automatically build an adapted WSGI file)
.. code-block:: console
$ ./manage.py make_web_conf --wsgi
Then configure the web server to host OpenStack dashboard via WSGI.
For apache2 web server, you may need to create
``/etc/apache2/sites-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
Or, if you previously generated an ``openstack_dashboard/wsgi/horizon.wsgi``
you can automatically generate an apache configuration file
.. code-block:: console
$ ./manage.py make_web_conf --apache > /etc/apache2/sites-available/horizon.conf
Same as above but if you want SSL support
.. code-block:: console
$ ./manage.py make_web_conf --apache --ssl --sslkey=/path/to/ssl/key --sslcert=/path/to/ssl/cert > /etc/apache2/sites-available/horizon.conf
By default the apache configuration will launch a number of apache processes
equal to the number of CPUs + 1 of the machine on which you launch the
``make_web_conf`` command. If the target machine is not the same or if you
want to specify the number of processes, add the ``--processes`` option
.. code-block:: console
$ ./manage.py make_web_conf --apache --processes 10 > /etc/apache2/sites-available/horizon.conf
#. Enable the above configuration and restart the web server
.. code-block:: console
$ sudo a2ensite horizon
$ sudo service apache2 restart
Next Steps
==========
* :doc:`settings` lists the available settings for horizon.
* :doc:`customizing` describes how to customize horizon.

14
doc/source/install/index.rst Normal file
View File

@ -0,0 +1,14 @@
==========================
Deployment & Configuration
==========================
This section provides instruction on configuring and deploying Horizon and its
plugins.
.. toctree::
:maxdepth: 1
deploy-guide.rst
settings.rst
customizing.rst
plugin-registry.rst

6
doc/source/plugin_registry.rst → doc/source/install/plugin-registry.rst
View File

@ -1,6 +1,6 @@
======================= ===============
Horizon Plugin Registry Plugin Registry
======================= ===============
.. Note:: .. Note::
Currently, Horizon plugins are responsible for their own compatibility. Currently, Horizon plugins are responsible for their own compatibility.

0
doc/source/topics/settings.rst → doc/source/install/settings.rst
View File

224
doc/source/topics/deployment.rst
View File

@ -1,224 +0,0 @@
=================
Deploying Horizon
=================
This guide aims to cover some common questions, concerns and pitfalls you
may encounter when deploying Horizon in a production environment.
.. seealso:: :doc:`settings`
.. note::
The Service Catalog returned by the Identity Service after a user
has successfully authenticated determines the dashboards and panels
that will be available within the OpenStack Dashboard. If you are not
seeing a particular service you expected (e.g. Object Storage/Swift or
Networking/Neutron) make sure your Service Catalog is configured correctly.
Prior to the Essex release of Horizon these features were controlled by
individual settings in the ``local_settings.py`` file. This code has been
long-since removed and those pre-Essex settings have no impact now.
Configure Your Identity Service Host
====================================
The one thing you *must* do in order to run Horizon is to specify the
host for your OpenStack Identity Service endpoint. To do this, set the value
of the ``OPENSTACK_HOST`` settings in your ``local_settings.py`` file.
Logging
=======
Logging is an important concern for production deployments, and the intricacies
of good logging configuration go far beyond what can be covered here. However
there are a few points worth noting about the logging included with Horizon,
how to customize it, and where other components may take over:
* Horizon's logging uses Django's logging configuration mechanism, which
can be customized in your ``local_settings.py`` file through the
``LOGGING`` dictionary.
* Horizon's default logging example sets the log level to ``"INFO"``, which is
a reasonable choice for production deployments. For development, however,
you may want to change the log level to ``"DEBUG"``.
* Horizon also uses a number of 3rd-party clients which log separately. The
log level for these can still be controlled through Horizon's ``LOGGING``
config, however behaviors may vary beyond Horizon's control.
* For more information regarding configuring logging in Horizon, please
read the `Django logging directive`_ and the `Python logging directive`_
documentation. Horizon is built on Python and Django.
.. _Django logging directive: https://docs.djangoproject.com/en/dev/topics/logging
.. _Python logging directive: http://docs.python.org/2/library/logging.html
File Uploads
============
Horizon allows users to upload files via their web browser to other OpenStack
services such as Glance and Swift. Files uploaded through this mechanism are
first stored on the Horizon server before being forwarded on - files are not
uploaded directly or streamed as Horizon receives them. As Horizon itself does
not impose any restrictions on the size of file uploads, production deployments
will want to consider configuring their server hosting the Horizon application
to enforce such a limit to prevent large uploads exhausting system resources
and disrupting services. Deployments using Apache2 can use the
`LimitRequestBody directive`_ to achieve this.
Uploads to the Glance image store service tend to be particularly large - in
the order of hundreds of megabytes to multiple gigabytes. Deployments are able
to disable local image uploads through Horizon by setting
``HORIZON_IMAGES_ALLOW_UPLOAD`` to ``False`` in your ``local_settings.py``
file.
.. note::
This will not disable image creation altogether, as this setting does not
affect images created by specifying an image location (URL) as the image source.
.. _LimitRequestBody directive: http://httpd.apache.org/docs/2.2/mod/core.html#limitrequestbody
Session Storage
===============
Horizon uses `Django's sessions framework`_ for handling user session data;
however that's not the end of the story. There are numerous session backends
available, which are controlled through the ``SESSION_ENGINE`` setting in
your ``local_settings.py`` file. What follows is a quick discussion of the
pros and cons of each of the common options as they pertain to deploying
Horizon specifically.
.. _Django's sessions framework: https://docs.djangoproject.com/en/dev/topics/http/sessions/
Local Memory Cache
------------------
Enabled by::
SESSION_ENGINE = 'django.contrib.sessions.backends.cache'
CACHES = {
'BACKEND': 'django.core.cache.backends.locmem.LocMemCache'
}
Local memory storage is the quickest and easiest session backend to set up,
as it has no external dependencies whatsoever. However, it has two significant
drawbacks:
* No shared storage across processes or workers.
* No persistence after a process terminates.
It is not recommended for production use, or even for serious development work.
For better options, read on.
Memcached
---------
Enabled by::
SESSION_ENGINE = 'django.contrib.sessions.backends.cache'
CACHES = {
'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache'
'LOCATION': 'my_memcached_host:11211',
}
External caching using an application such as memcached offers persistence
and shared storage, and can be very useful for small-scale deployment and/or
development. However, for distributed and high-availability scenarios
memcached has inherent problems which are beyond the scope of this
documentation.
Memcached is an extremely fast and efficient cache backend for cases where it
fits the deployment need. But it's not appropriate for all scenarios.
Requirements:
* Memcached service running and accessible.
* Python memcached module installed.
Database
--------
Enabled by::
SESSION_ENGINE = 'django.core.cache.backends.db.DatabaseCache'
DATABASES = {
'default': {
# Database configuration here
}
}
Database-backed sessions are scalable (using an appropriate database strategy),
persistent, and can be made high-concurrency and highly-available.
The downside to this approach is that database-backed sessions are one of the
slower session storages, and incur a high overhead under heavy usage. Proper
configuration of your database deployment can also be a substantial
undertaking and is far beyond the scope of this documentation.
Cached Database
---------------
To mitigate the performance issues of database queries, you can also consider
using Django's ``cached_db`` session backend which utilizes both your database
and caching infrastructure to perform write-through caching and efficient
retrieval. You can enable this hybrid setting by configuring both your database
and cache as discussed above and then using::
SESSION_ENGINE = "django.contrib.sessions.backends.cached_db"
Cookies
-------
``signed_cookies`` is a session backend that is available to you which avoids
server load and scaling problems.
This backend stores session data in a cookie which is stored by the
user's browser. The backend uses a cryptographic signing technique to ensure
session data is not tampered with during transport (**this is not the same
as encryption, session data is still readable by an attacker**).
The pros of this session engine are that it doesn't require any additional
dependencies or infrastructure overhead, and it scales indefinitely as long
as the quantity of session data being stored fits into a normal cookie.
The biggest downside is that it places session data into storage on the user's
machine and transports it over the wire. It also limits the quantity of
session data which can be stored.
For a thorough discussion of the security implications of this session backend,
please read the `Django documentation on cookie-based sessions`_.
.. _Django documentation on cookie-based sessions: https://docs.djangoproject.com/en/dev/topics/http/sessions/#using-cookie-based-sessions
Secure Site Recommendations
---------------------------
When implementing Horizon for public usage, with the website served through
HTTPS, it is recommended that the following settings are applied.
To help protect the session cookies from `cross-site scripting`_, add the
following to ``local_settings.py``::
CSRF_COOKIE_HTTPONLY = True
SESSION_COOKIE_HTTPONLY = True
Client-side JavaScript will not be able to access the cookie if this set to
True. Note that the HTTPOnly is a flag included in Set-Cookie HTTP response
header and is not honored consistently by all browsers.
Additionally, adding the following flags to ``local_settings.py`` marks the
cookies as secure, which ensures that the cookie is only sent under an HTTPS
connection::
CSRF_COOKIE_SECURE = True
SESSION_COOKIE_SECURE = True
You can also disable `browser autocompletion`_ for the authentication form by
modifying the ``HORIZON_CONFIG`` dictionary in ``local_settings.py`` by adding
the key ``password_autocomplete`` with the value ``off`` as shown here::
HORIZON_CONFIG = {
...
'password_autocomplete': 'off',
}
.. _cross-site scripting: https://www.owasp.org/index.php/HttpOnly
.. _browser autocompletion: https://wiki.mozilla.org/The_autocomplete_attribute_and_web_documents_using_XHTML

1
doc/source/topics/index.rst
View File

@ -17,3 +17,4 @@ the following topic guides.
javascript_testing javascript_testing
styling styling
translation translation
packaging

125
doc/source/topics/install.rst
View File

@ -1,125 +0,0 @@
==================
Installing Horizon
==================
This page covers the basic installation of horizon, the OpenStack dashboard.
.. _system-requirements-label:
System Requirements
===================
* Python 2.7
* Django 1.7 or 1.8
* Minimum required set of running OpenStack services are:
* nova: OpenStack Compute
* keystone: OpenStack Identity
* glance: OpenStack Image service
* neutron: OpenStack Networking (unless nova-network is used)
* All other services are optional.
Horizon supports the following services in the Juno release.
If the keystone endpoint for a service is configured,
horizon detects it and enables its support automatically.
* swift: OpenStack Object Storage
* cinder: OpenStack Block Storage
* heat: Orchestration
* ceilometer: Telemetry
* trove: Database service for OpenStack
* sahara: Data processing service for OpenStack
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
$ tox -e manage -- compilemessages
This command compiles translation message catalogs within Python
virtualenv named ``.venv``. After this step, you can remove
``.venv`` directory safely.
2. Install the horizon python module into your system. Run the following
in the top directory::
$ sudo pip install -c http://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt?h=stable/<release> .
Where "<release>" is the release you are installing (eg. "newton",
"ocata", ...)
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. Optional: Django has a compressor feature that performs many enhancements
for the delivery of static files, including standardization and
minification/uglification. This processing can be run either online or
offline (pre-processed). Letting the compression process occur at runtime
will incur processing and memory use when the resources are first requested;
doing it ahead of time removes those runtime penalties.
If you want the static files to be processed before server runtime, you'll
need to configure your local_settings.py to specify
``COMPRESS_OFFLINE = True``, then run the following commands::
$ ./manage.py collectstatic
$ ./manage.py compress
5. 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
You will either use the provided ``openstack_dashboard/wsgi/django.wsgi`` or
generate an ``openstack_dashboard/wsgi/horizon.wsgi`` file with the
following command (which detects if you use a virtual environment or not to
automatically build an adapted wsgi file)::
$ ./manage.py make_web_conf --wsgi
Then configure the web server to host OpenStack dashboard via WSGI.
For apache2 web server, you may need to create
``/etc/apache2/sites-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
Or, if you previously generated an ``openstack_dashboard/wsgi/horizon.wsgi``
you can automatically generate an apache configuration file::
$ ./manage.py make_web_conf --apache > /etc/apache2/sites-available/horizon.conf
Same as above but if you want ssl support::
$ ./manage.py make_web_conf --apache --ssl --sslkey=/path/to/ssl/key --sslcert=/path/to/ssl/cert > /etc/apache2/sites-available/horizon.conf
By default the apache configuration will launch a number of apache processes
equal to the number of CPUs + 1 of the machine on which you launch the
make_web_conf command. If the target machine is not the same or if you want
to specify the number of processes, add the --processes option::
$ ./manage.py make_web_conf --apache --processes 10 > /etc/apache2/sites-available/horizon.conf
6. 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.

3
doc/source/topics/styling.rst
View File

@ -4,7 +4,8 @@ Styling in Horizon (SCSS)
Horizon uses `SCSS`_ (not to be confused with Sass) to style its HTML. This Horizon uses `SCSS`_ (not to be confused with Sass) to style its HTML. This
guide is targeted at developers adding code to upstream Horizon. For guide is targeted at developers adding code to upstream Horizon. For
information on creating your own branding/theming, see :doc:`customizing`. information on creating your own branding/theming, see
:doc:`Customizing Horizon </install/customizing>`.
.. _SCSS: http://sass-lang.com/guide .. _SCSS: http://sass-lang.com/guide

2
doc/source/tutorials/plugin.rst
View File

@ -121,7 +121,7 @@ The enabled folder contains the configuration file(s) that registers your
plugin with Horizon. The file is prefixed with an alpha-numeric string that plugin with Horizon. The file is prefixed with an alpha-numeric string that
determines the load order of your plugin. For more information on what you can determines the load order of your plugin. For more information on what you can
include in this file, see pluggable settings in include in this file, see pluggable settings in
:doc:`Settings and Configuration </topics/settings>` :doc:`Settings and Configuration </install/settings>`
_31000_myplugin.py:: _31000_myplugin.py::