openstack-manuals/doc/install-guide/section_dashboard-install.xml

<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  version="5.0"
  xml:id="install_dashboard">
  <?dbhtml stop-chunking?>
  <title>Install and configure</title>
  <para>This section describes how to install and configure the dashboard
    on the controller node.</para>
  <para>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
    <link xlink:href="http://docs.openstack.org/developer/horizon/topics/deployment.html">developer documentation</link>.</para>
  <para>This section assumes proper installation, configuration, and
      operation of the Identity service using the Apache HTTP server and
      Memcached as described in <xref linkend="keystone-install"/>.</para>
  <procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
    <title>To install the dashboard components</title>
    <step>
      <para>Install the packages:</para>
      <screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install openstack-dashboard</userinput></screen>
      <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-dashboard httpd mod_wsgi memcached python-memcached</userinput></screen>
      <screen os="sles;opensuse"><prompt>#</prompt> <userinput>zypper install openstack-dashboard apache2-mod_wsgi memcached python-python-memcached</userinput></screen>
      <note os="ubuntu">
        <para>Ubuntu installs the
          <package>openstack-dashboard-ubuntu-theme</package> 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.</para>
      </note>
    </step>
  </procedure>
  <procedure os="debian">
    <title>To install the dashboard components</title>
     <step>
       <para>Install the packages:</para>
       <screen><prompt>#</prompt> <userinput>apt-get install openstack-dashboard-apache</userinput></screen>
     </step>
     <step>
       <para>Respond to prompts for web server configuration.</para>
       <note>
         <para>The automatic configuration process generates a self-signed
           SSL certificate. Consider obtaining an official certificate for
           production environments.</para>
       </note>
     </step>
   </procedure>
   <procedure>
     <title>To configure the dashboard</title>
     <step os="sles;opensuse">
       <para>Configure the web server:</para>
       <screen><prompt>#</prompt> <userinput>cp /etc/apache2/conf.d/openstack-dashboard.conf.sample \
  /etc/apache2/conf.d/openstack-dashboard.conf</userinput>
<prompt>#</prompt> <userinput>a2enmod rewrite;a2enmod ssl;a2enmod wsgi</userinput></screen>
     </step>
     <step>
       <para os="ubuntu;debian">Edit the
         <filename>/etc/openstack-dashboard/local_settings.py</filename>
         file and complete the following actions:</para>
       <para os="rhel;centos;fedora">Edit the
         <filename>/etc/openstack-dashboard/local_settings</filename>
         file and complete the following actions:</para>
       <para os="sles;opensuse">Edit the
         <filename>/srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py</filename>
         file and complete the following actions:</para>
       <substeps>
         <step>
           <para>Configure the dashboard to use OpenStack services on the
             <literal>controller</literal> node:</para>
           <programlisting language="python">OPENSTACK_HOST = "<replaceable>controller</replaceable>"</programlisting>
         </step>
         <step>
           <para>Allow all hosts to access the dashboard:</para>
           <programlisting language="python">ALLOWED_HOSTS = '*'</programlisting>
         </step>
         <step>
           <para>Configure the <application>memcached</application> session
             storage service:</para>
           <programlisting language="python">CACHES = {
   'default': {
       'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
       'LOCATION': '127.0.0.1:11211',
   }
}</programlisting>
           <note>
             <para>Comment out any other session storage configuration.</para>
           </note>
           <note os="sles;opensuse">
             <para>By default, SLES and openSUSE use a SQL database for session
               storage. For simplicity, we recommend changing the configuration
               to use <application>memcached</application> for session
               storage.</para>
          </note>
        </step>
        <step>
          <para>Configure <literal>user</literal> as the default role for
            users that you create via the dashboard:</para>
          <programlisting language="python">OPENSTACK_KEYSTONE_DEFAULT_ROLE = "user"</programlisting>
         </step>
        <step>
          <para>Optionally, configure the time zone:</para>
          <programlisting language="python">TIME_ZONE = "<replaceable>TIME_ZONE</replaceable>"</programlisting>
          <para>Replace <replaceable>TIME_ZONE</replaceable> with an
            appropriate time zone identifier. For more information, see the
           <link xlink:href="http://en.wikipedia.org/wiki/List_of_tz_database_time_zones"
           >list of time zones</link>.</para>
        </step>
      </substeps>
    </step>
  </procedure>
  <procedure>
    <title>To finalize installation</title>
    <step os="rhel;centos;fedora">
      <para>On RHEL and CentOS, configure SELinux to permit the web server
        to connect to OpenStack services:</para>
      <screen><prompt>#</prompt> <userinput>setsebool -P httpd_can_network_connect on</userinput></screen>
    </step>
    <step os="rhel;centos;fedora">
      <para>Due to a packaging bug, the dashboard CSS fails to load properly.
        Run the following command to resolve this issue:</para>
      <screen><prompt>#</prompt> <userinput>chown -R apache:apache /usr/share/openstack-dashboard/static</userinput></screen>
      <para>For more information, see the
        <link xlink:href="https://bugzilla.redhat.com/show_bug.cgi?id=1150678"
        >bug report</link>.</para>
    </step>
    <step os="ubuntu;debian">
      <para>Reload the web server configuration:</para>
      <screen><prompt>#</prompt> <userinput>service apache2 reload</userinput></screen>
    </step>
    <step os="rhel;centos;fedora;sles;opensuse">
      <para>Start the web server and session storage service and configure
        them to start when the system boots:</para>
      <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>systemctl enable httpd.service memcached.service</userinput>
<prompt>#</prompt> <userinput>systemctl start httpd.service memcached.service</userinput></screen>
      <screen os="opensuse;sles"><prompt>#</prompt> <userinput>systemctl enable apache2.service memcached.service</userinput>
<prompt>#</prompt> <userinput>systemctl start apache2.service memcached.service</userinput></screen>
    </step>
  </procedure>
</section>