From 8b5ec5a78eb2817bcd6304a82ed0e39b6bf2b149 Mon Sep 17 00:00:00 2001 From: darrenchan Date: Wed, 8 Oct 2014 13:55:15 +1100 Subject: [PATCH] Improvements to the dashboard installation section Improved dashboard content in the installation guide as follows: 1) Restructured steps for consistency with similar sections. 2) Updated list of packages to install. 3) Adjusted configuration on all distributions to use memcached for session storage to simplify installation. 4) Clarified instructions for access permissions. 5) Split verification step into separate section for consistency with other chapters. 6) Changed removal of Ubuntu theme package from 'required' to 'optional' based on user experience. 7) Added workaround for RDO packaging issues. This patch includes changes for Juno. Change-Id: Iecb1cff57853b097ba2ee0a5016438190ff8d920 Implements: blueprint installation-guide-improvements Co-Authored-By: Matt Kassawara --- doc/install-guide/ch_horizon.xml | 2 +- .../section_dashboard-install.xml | 280 ++++++++---------- .../section_dashboard-verify.xml | 24 ++ 3 files changed, 152 insertions(+), 154 deletions(-) create mode 100644 doc/install-guide/section_dashboard-verify.xml diff --git a/doc/install-guide/ch_horizon.xml b/doc/install-guide/ch_horizon.xml index 44e67386ed..a2c27d0dfb 100644 --- a/doc/install-guide/ch_horizon.xml +++ b/doc/install-guide/ch_horizon.xml @@ -19,7 +19,7 @@ - +
Next steps Your OpenStack environment now includes the dashboard. You can diff --git a/doc/install-guide/section_dashboard-install.xml b/doc/install-guide/section_dashboard-install.xml index 51465623d0..a0b280a3c7 100644 --- a/doc/install-guide/section_dashboard-install.xml +++ b/doc/install-guide/section_dashboard-install.xml @@ -4,166 +4,140 @@ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="install_dashboard"> - - Install the dashboard - Before you can install and configure the dashboard, meet the requirements in . - - When you install the dashboard with only OpenStack Object Storage and Identity, the - dashboard does not show projects and is unusable. - - For more information about how to deploy the dashboard, see deployment topics in the developer documentation. - - - Install the dashboard on the node that can contact the Identity service as - root: - # apt-get install apache2 memcached libapache2-mod-wsgi openstack-dashboard - # yum install memcached python-memcached mod_wsgi openstack-dashboard - # zypper install memcached python-python-memcached apache2-mod_wsgi openstack-dashboard openstack-dashboard-test - - Note for Ubuntu users - The openstack-dashboard-ubuntu-theme package prevents - translations, several menus, and the network map from rendering correctly. - Remove this package: - # apt-get remove --purge openstack-dashboard-ubuntu-theme - - - Note for Debian users - To install the Apache package: - # apt-get install openstack-dashboard-apache - This command installs and configures Apache correctly, provided that the user - asks for it during the debconf prompts. The default SSL - certificate is self-signed, and it is probably wise to have it signed by a root - Certificate Authority (CA). - - - - Modify the value of CACHES['default']['LOCATION'] in /etc/openstack-dashboard/local_settings.py/etc/openstack-dashboard/local_settings/srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py - to match the ones set in /etc/memcached.conf/etc/sysconfig/memcached. - Open /etc/openstack-dashboard/local_settings.py - /etc/openstack-dashboard/local_settings - and look for this line: - CACHES = \ - {'default': {'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache', - 'LOCATION': '127.0.0.1:11211'}} - - Notes - - - The address and port must match the ones set in /etc/memcached.conf/etc/sysconfig/memcached. - If you change the memcached settings, you must restart the Apache web - server for the changes to take effect. - - - You can use options other than memcached option for session storage. - Set the session back-end through the - SESSION_ENGINE option. - - - To change the timezone, use the dashboard or edit the /etc/openstack-dashboard/local_settings/etc/openstack-dashboard/local_settings.py/srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py - file. - Change the following parameter: TIME_ZONE = "UTC" - - - - - - Update the ALLOWED_HOSTS in - local_settings.py to include the addresses from which you - want to access the dashboard. - Edit /etc/openstack-dashboard/local_settings/etc/openstack-dashboard/local_settings.py/srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py: - ALLOWED_HOSTS = ['localhost', 'my-desktop'] - - - This guide assumes that you are running the dashboard on the controller node. You - can easily run the dashboard on a separate server by changing the appropriate - settings in local_settings.py. - Edit /etc/openstack-dashboard/local_settings/etc/openstack-dashboard/local_settings.py/srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py - and change OPENSTACK_HOST to the host name of your Identity - service: - OPENSTACK_HOST = "controller" - - - Configure Apache: - # cp /etc/apache2/conf.d/openstack-dashboard.conf.sample \ - /etc/apache2/conf.d/openstack-dashboard.conf + + Install and configure + This section describes how to install and configure the dashboard + on the controller node. + Before you proceed, verify that your system meets the requirements + in . Also, the dashboard + relies on functional core services including Identity, Image Service, + Compute, and either Networking (neutron) or legacy networking + (nova-network). Environments with stand-alone services such as Object + Storage cannot use the dashboard. For more information, see the + developer documentation. + + To install the dashboard components + + Install the packages: + # apt-get install openstack-dashboard apache2 libapache2-mod-wsgi memcached python-memcache + # yum install openstack-dashboard httpd mod_wsgi memcached python-memcached + # zypper install openstack-dashboard apache2-mod_wsgi memcached python-python-memcached \ + openstack-dashboard-test + + Ubuntu installs the + openstack-dashboard-ubuntu-theme package + as a dependency. Some users reported issues with this theme in + previous releases. If you encounter issues, remove this package + to restore the original OpenStack theme. + + + + + To install the dashboard components + + Install the packages: + # apt-get install openstack-dashboard-apache + + + Respond to prompts for web server configuration. + + The automatic configuration process generates a self-signed + SSL certificate. Consider obtaining an official certificate for + production environments. + + + + + To configure the dashboard + + Configure the web server: + # cp /etc/apache2/conf.d/openstack-dashboard.conf.sample \ + /etc/apache2/conf.d/openstack-dashboard.conf # a2enmod rewrite;a2enmod ssl;a2enmod wsgi - - - By default, the openstack-dashboard package enables a database - as a session store. - Before you continue, you can either: - - - Change the session store. See Set up session - storage in the Cloud Administrator - Guide. - - - Complete the database session store set up. See - Initialize and configure the - database. - - - - - Ensure that the SELinux policy of the system is configured to allow network - connections to the HTTP server: - # setsebool -P httpd_can_network_connect on + + + Edit the + /etc/openstack-dashboard/local_settings.py + file and complete the following actions: + Edit the + /etc/openstack-dashboard/local_settings + file and complete the following actions: + Edit the + /srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py + file and complete the following actions: + + + Configure the dashboard to use OpenStack services on the + controller node: + OPENSTACK_HOST = "controller" + + + Allow all hosts to access the dashboard: + ALLOWED_HOSTS = ['*'] + + + Configure the memcached session + storage service: + CACHES = { + 'default': { + 'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache', + 'LOCATION': '127.0.0.1:11211', + } +} + + Comment out any other session storage configuration. + + + By default, SLES and openSUSE use a SQL database for session + storage. For simplicity, we recommend changing the configuration + to use memcached for session + storage. + - Start the Apache web server and memcached: - # service apache2 restart + Optionally, configure the time zone: + TIME_ZONE = "TIME_ZONE" + Replace TIME_ZONE with an + appropriate time zone identifier. For more information, see the + list of time zones. + + + + + + To finalize installation + + On RHEL and CentOS, configure SELinux to permit the web server + to connect to OpenStack services: + # setsebool -P httpd_can_network_connect on + + + Due to a packaging bug, the dashboard CSS fails to load properly. + Run the following command to resolve this issue: + # chown -R apache:apache /usr/share/openstack/static + For more information, see the + bug report. + + + Restart the web server and session storage service: + # service apache2 restart # service memcached restart - # systemctl enable httpd.service memcached.service + + + Start the web server and session storage service and configure + them to start when the system boots: + # systemctl enable httpd.service memcached.service # systemctl start httpd.service memcached.service - On SLES: - # service apache2 start + On SLES: + # service apache2 start # service memcached start # chkconfig apache2 on # chkconfig memcached on - On openSUSE: - # systemctl enable apache2.service memcached.service + On openSUSE: + # systemctl enable apache2.service memcached.service # systemctl start apache2.service memcached.service - - - You can now access the dashboard at http://controller/horizon - https://controller/ - http://controller/dashboard - http://controller. - Log in with credentials for any user that you created with OpenStack - Identity. - - + +
diff --git a/doc/install-guide/section_dashboard-verify.xml b/doc/install-guide/section_dashboard-verify.xml new file mode 100644 index 0000000000..6214e12538 --- /dev/null +++ b/doc/install-guide/section_dashboard-verify.xml @@ -0,0 +1,24 @@ + +
+ + Verify operation + This section describes how to verify operation of the + dashboard. + + + Access the dashboard using a web browser: + http://controller/horizon + https://controller/ + http://controller/dashboard + http://controller. + + + Authenticate using admin or + demo user credentials. + + +