diff --git a/README.rst b/README.rst index f133ba266b..a93eb423d7 100644 --- a/README.rst +++ b/README.rst @@ -18,11 +18,12 @@ web-based interactions with the various OpenStack projects. 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 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 ============================== diff --git a/doc/source/index.rst b/doc/source/index.rst index bc46ce223a..faa9d7c00d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -36,14 +36,9 @@ Using Horizon How to use Horizon in your own projects. .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - topics/install - topics/deployment - topics/settings - topics/customizing - topics/packaging - browser_support + install/index Developer Docs ============== @@ -59,7 +54,7 @@ the following documentation is provided. quickstart contributing testing - plugin_registry + browser_support tutorials/index topics/index ref/index diff --git a/doc/source/topics/customizing.rst b/doc/source/install/customizing.rst similarity index 100% rename from doc/source/topics/customizing.rst rename to doc/source/install/customizing.rst diff --git a/doc/source/install/deploy-guide.rst b/doc/source/install/deploy-guide.rst new file mode 100644 index 0000000000..87e66b35fe --- /dev/null +++ b/doc/source/install/deploy-guide.rst @@ -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 `. + +.. _system-requirements-label: + +System Requirements +=================== + +* Python 2.7 +* Django 1.8 +* An accessible `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 `_: Block Storage + * `glance `_: Image Management + * `heat `_: Orchestration + * `neutron `_: Networking + * `nova `_: Compute + * `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 "" 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/ --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/ . + +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. diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 0000000000..02dae6b2db --- /dev/null +++ b/doc/source/install/index.rst @@ -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 diff --git a/doc/source/plugin_registry.rst b/doc/source/install/plugin-registry.rst similarity index 99% rename from doc/source/plugin_registry.rst rename to doc/source/install/plugin-registry.rst index 8e66251e82..9a04973b83 100644 --- a/doc/source/plugin_registry.rst +++ b/doc/source/install/plugin-registry.rst @@ -1,6 +1,6 @@ -======================= -Horizon Plugin Registry -======================= +=============== +Plugin Registry +=============== .. Note:: Currently, Horizon plugins are responsible for their own compatibility. diff --git a/doc/source/topics/settings.rst b/doc/source/install/settings.rst similarity index 100% rename from doc/source/topics/settings.rst rename to doc/source/install/settings.rst diff --git a/doc/source/topics/deployment.rst b/doc/source/topics/deployment.rst deleted file mode 100644 index df077b1c30..0000000000 --- a/doc/source/topics/deployment.rst +++ /dev/null @@ -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 diff --git a/doc/source/topics/index.rst b/doc/source/topics/index.rst index 8f9b8fecd1..ea7fbcb6cf 100644 --- a/doc/source/topics/index.rst +++ b/doc/source/topics/index.rst @@ -17,3 +17,4 @@ the following topic guides. javascript_testing styling translation + packaging diff --git a/doc/source/topics/install.rst b/doc/source/topics/install.rst deleted file mode 100644 index b3bd643508..0000000000 --- a/doc/source/topics/install.rst +++ /dev/null @@ -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/ . - - Where "" 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. diff --git a/doc/source/topics/styling.rst b/doc/source/topics/styling.rst index 0992938b9d..3ce552d307 100644 --- a/doc/source/topics/styling.rst +++ b/doc/source/topics/styling.rst @@ -4,7 +4,8 @@ Styling in Horizon (SCSS) 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 -information on creating your own branding/theming, see :doc:`customizing`. +information on creating your own branding/theming, see +:doc:`Customizing Horizon `. .. _SCSS: http://sass-lang.com/guide diff --git a/doc/source/tutorials/plugin.rst b/doc/source/tutorials/plugin.rst index 004fc6a0c6..b5c5f4c13d 100644 --- a/doc/source/tutorials/plugin.rst +++ b/doc/source/tutorials/plugin.rst @@ -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 determines the load order of your plugin. For more information on what you can include in this file, see pluggable settings in -:doc:`Settings and Configuration ` +:doc:`Settings and Configuration ` _31000_myplugin.py::