Skip to content

Commit

Permalink
adding user guide files
Browse files Browse the repository at this point in the history
bug: #1110146

Change-Id: If68a092011c639c80de9059ae50ae72ea60783a8
  • Loading branch information
dian4554 committed Jun 4, 2013
1 parent eab4fc6 commit f7593c4
Show file tree
Hide file tree
Showing 11 changed files with 265 additions and 220 deletions.
Expand Up @@ -6,9 +6,8 @@
<title>OpenStack Dashboard</title>
<para>The OpenStack Dashboard service provides users of the cloud environment with a web-accessible GUI as an alternative
to using the command-line tools.</para>
<para>To enable it, install the Horizon package and its dependencies:
<screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install openstack-dashboard memcached python-memcache</userinput></screen>
<screen os="centos;rhel;fedora"><prompt>#</prompt> <userinput>yum install httpd memcached
<para>To enable it, install the Horizon package and its
dependencies: <screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install openstack-dashboard memcached python-memcache</userinput></screen><screen os="centos;rhel;fedora"><prompt>#</prompt> <userinput>yum install httpd memcached
( cat | sudo tee -a /etc/openstack-dashboard/local_settings ) &lt;&lt;EOF
DATABASES = {
'default': {
Expand All @@ -22,19 +21,25 @@ DATABASES = {
}
EOF</userinput></screen>
<note os="ubuntu">
<para>Optional, but recommended: remove the <literal>openstack-dashboard-ubuntu-theme</literal> package.
This theme prevents several menus as well as the network map from rendering correctly:
<screen><userinput>apt-get remove --purge openstack-dashboard-ubuntu-theme</userinput></screen>
<para>Optional, but recommended: remove the
<literal>openstack-dashboard-ubuntu-theme</literal>
package. This theme prevents several menus as well as
the network map from rendering correctly:
<screen><userinput>apt-get remove --purge openstack-dashboard-ubuntu-theme</userinput></screen>
</para>
</note>OpenStack Dashboard is now available at <emphasis
role="bold">http://cloud/horizon</emphasis>. We can login
with the <emphasis role="bold">admin</emphasis> / <emphasis
role="bold">password</emphasis> credentials or <emphasis
role="bold">demo</emphasis> / <emphasis role="bold"
>password</emphasis>. <note>
<para>Check the
<literal>/var/log/apache/error.log</literal> file
for errors that wold prevent either the Apache service
or the Dashboard service from successfully
starting.</para>
</note>

OpenStack Dashboard is now available at <emphasis role="bold">http://cloud/horizon</emphasis>.
We can login with the <emphasis role="bold">admin</emphasis> / <emphasis role="bold">password</emphasis> credentials
or <emphasis role="bold">demo</emphasis> / <emphasis role="bold">password</emphasis>.

<note><para>Check the <literal>/var/log/apache/error.log</literal> file for errors that wold prevent
either the Apache service or the Dashboard service from successfully starting.</para></note>
</para>
</para>

</section>

File renamed without changes.
Expand Up @@ -7,9 +7,7 @@
<title>Installing the OpenStack Dashboard</title>
<para>OpenStack has components that provide a view of the
OpenStack installation such as a Django-built website that
serves as a dashboard.</para>
<section xml:id="about-the-dashboard">
<title>About the Dashboard</title>
serves as a dashboard. </para>
<para>You can use a dashboard interface with an OpenStack
Compute installation with a web-based console provided by
the Openstack-Dashboard project. It provides web-based
Expand All @@ -20,7 +18,29 @@
>https://github.com/openstack/horizon/</link>. These
instructions are for an example deployment configured with
an Apache web server. </para>
</section>
<section xml:id="task_flow"><title>Dashboard Installation Task Flow</title>
<para>To install the OpenStack Dashboard, complete the
following high-level steps: </para>
<orderedlist>
<listitem>
<para>Meet the system requirements for the dashboard.</para>
</listitem>
<listitem>
<para>Install the OpenStack Dashboard framework,
including Apache and related modules.</para>
</listitem>
<listitem>
<para>Configure the dashboard.</para>
</listitem>
<listitem>
<para>Restart and run the Apache server.</para>
</listitem>
<listitem>
<para>Deploy the dashboard. See <link
xlink:href="http://docs.openstack.org/developer/horizon/topics/deployment.html"
>Deploying Horizon</link>.</para>
</listitem>
</orderedlist></section>
<xi:include href="../common/dashboard-system-reqs.xml"/>
<xi:include href="../common/dashboard-install.xml"/>
<xi:include href="../common/dashboard-configure.xml"/>
Expand Down
162 changes: 79 additions & 83 deletions doc/src/docbkx/common/dashboard-configure.xml
Expand Up @@ -3,94 +3,90 @@
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">
<title>Configuring the Dashboard</title>
<orderedlist>
<listitem>
<para><emphasis role="bold">Simple deployment (HTTP)</emphasis></para>
<para>Specify the host for your OpenStack Identity Service endpoint in the
<filename>/etc/openstack-dashboard/local_settings.py</filename> file with the
OPENSTACK_HOST setting. An example is included: </para>
<title>Configure the Dashboard</title>
<para>You can configure the dashboard for a simple HTTP deployment or a secured HTTPS deployment. While the standard installation uses a non-encrypted
HTTP channel, you can enable SSL support for the
dashboard. </para>
<section xml:id="dashboard-config-http"><title>Configure the Dashboard for HTTP</title><procedure><title>To configure the dashboard for HTTP:</title>
<step>
<para>Specify the host for your OpenStack Identity Service
endpoint in the
<filename>/etc/openstack-dashboard/local_settings.py</filename>
file with the <literal>OPENSTACK_HOST</literal>
setting. </para>
<para>The following example shows this setting: </para>
<programlisting><xi:include parse="text" href="samples/local_settings.py"/></programlisting>
<para>The HORIZON_CONFIG dictionary contains all the settings for
the Dashboard. Whether or not a service is in the Dashboard
depends on the Service Catalog configuration in the Identity
service. Refer to <link xlink:href="http://docs.openstack.org/developer/horizon/topics/settings.html">Horizon Settings and Configuration</link> for the
full listing.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Secured deployment (HTTPS)</emphasis></para>
<para>While the standard installation uses a non-encrypted
channel (HTTP), it is possible to enable the SSL
support for the OpenStack Dashboard. In the following
example, we use the domain
"http://openstack.example.com", make sure to use one
that fits your current setup.</para>
<itemizedlist>
<listitem>
<para> In<filename>/etc/openstack-dashboard/local_settings.py</filename> update
the following
directive:<programlisting>USE_SSL = True</programlisting></para>
</listitem>
<listitem>
<para> Edit <filename>/etc/apache2/ports.conf</filename> and add the following
line: <programlisting>NameVirtualHost *:443</programlisting></para>
</listitem>
<listitem>
<para>
Edit <filename>/etc/apache2/conf.d/openstack-dashboard.conf:</filename></para>

<para> Before:
<programlisting>WSGIScriptAlias / /usr/share/openstack-dashboard/openstack_dashboard/wsgi/django.wsgi
<para>The <literal>HORIZON_CONFIG</literal> dictionary
contains all the settings for the dashboard. Whether
or not a service is in the Dashboard depends on the
Service Catalog configuration in the Identity service.
For the full listing, see <link
xlink:href="http://docs.openstack.org/developer/horizon/topics/settings.html"
>Horizon Settings and Configuration</link>.</para>
</step></procedure></section>
<section xml:id="dashboard-config-https"><title>Configure the Dashboard for HTTPS</title><procedure><title>To configure the dashboard for HTTPS:</title>
<para>The following example uses the domain,
"http://openstack.example.com." Use a domain that fits
your current setup.</para>
<step>


<para> In<filename>/etc/openstack-dashboard/local_settings.py</filename> update
the following
directive:<programlisting>USE_SSL = True</programlisting></para>
</step>
<step>
<para> Edit <filename>/etc/apache2/ports.conf</filename> and add the following
line: <programlisting>NameVirtualHost *:443</programlisting></para>
</step>
<step>
<para>
Edit <filename>/etc/apache2/conf.d/openstack-dashboard.conf:</filename></para>

<para> Before:
<programlisting>WSGIScriptAlias / /usr/share/openstack-dashboard/openstack_dashboard/wsgi/django.wsgi
WSGIDaemonProcess horizon user=www-data group=www-data processes=3 threads=10
Alias /static /usr/share/openstack-dashboard/openstack_dashboard/static/
&lt;Directory /usr/share/openstack-dashboard/openstack_dashboard/wsgi&gt;
Order allow,deny
Allow from all
&lt;/Directory&gt;
</programlisting>
</para>

<para> After:
<programlisting>&lt;VirtualHost *:80&gt;
ServerName openstack.example.com
RedirectPermanent / https://openstack.example.com
Order allow,deny
Allow from all
&lt;/Directory&gt; </programlisting></para>

<para> After:
<programlisting>&lt;VirtualHost *:80&gt;
ServerName openstack.example.com
RedirectPermanent / https://openstack.example.com
&lt;/VirtualHost&gt;
&lt;VirtualHost *:443&gt;
ServerName openstack.example.com
ServerName openstack.example.com

SSLEngine On
SSLCertificateFile /etc/apache2/SSL/openstack.example.com.crt
SSLCACertificateFile /etc/apache2/SSL/openstack.example.com.crt
SSLCertificateKeyFile /etc/apache2/SSL/openstack.example.com.key
SetEnvIf User-Agent &quot;.*MSIE.*&quot; nokeepalive ssl-unclean-shutdown
SSLEngine On
SSLCertificateFile /etc/apache2/SSL/openstack.example.com.crt
SSLCACertificateFile /etc/apache2/SSL/openstack.example.com.crt
SSLCertificateKeyFile /etc/apache2/SSL/openstack.example.com.key
SetEnvIf User-Agent &quot;.*MSIE.*&quot; nokeepalive ssl-unclean-shutdown

WSGIScriptAlias / /usr/share/openstack-dashboard/openstack_dashboard/wsgi/django.wsgi
WSGIDaemonProcess horizon user=www-data group=www-data processes=3 threads=10
Alias /static /usr/share/openstack-dashboard/openstack_dashboard/static/
&lt;Directory /usr/share/openstack-dashboard/openstack_dashboard/wsgi&gt;
Order allow,deny
Allow from all
&lt;/Directory&gt;
&lt;/VirtualHost&gt;
</programlisting>
</para>

<para>In this configuration, we instruct Apache to
listen on the port 443 and to redirect all the
hits to the HTTPs protocol for all the
non-secured requests. In the secured section,
we define as well the private key, the public
key, and the certificate to use.</para>

</listitem>
<listitem>
<para>Finally restart Apache and memcached:</para>
<screen><prompt>#</prompt> <userinput>service apache2 restart</userinput>
<prompt>#</prompt> <userinput>service memcached restart</userinput> </screen>

</listitem>
</itemizedlist>
<para>You should now be redirected to the HTTPs page if you call the HTTP version of the dashboard via your browser.</para>
</listitem>
</orderedlist>
</section>
WSGIScriptAlias / /usr/share/openstack-dashboard/openstack_dashboard/wsgi/django.wsgi
WSGIDaemonProcess horizon user=www-data group=www-data processes=3 threads=10
Alias /static /usr/share/openstack-dashboard/openstack_dashboard/static/
&lt;Directory /usr/share/openstack-dashboard/openstack_dashboard/wsgi&gt;
Order allow,deny
Allow from all
&lt;/Directory&gt;
&lt;/VirtualHost&gt; </programlisting></para>
<para>In this configuration, Apache listens on the port 443
and redirects all the hits to the HTTPS protocol
for all the non-secured requests. In the secured
section, the private key, public key, and
certificate to use are defined.</para>
</step>
<step>
<para>Restart Apache and memcached:</para>
<screen><prompt>#</prompt> <userinput>service apache2 restart</userinput>
<prompt>#</prompt> <userinput>service memcached restart</userinput></screen>
<para>If you call the HTTP version of the dashboard
through your browser, you are redirected to the HTTPS
page.</para>
</step>
</procedure></section>
</section>
71 changes: 36 additions & 35 deletions doc/src/docbkx/common/dashboard-install.xml
@@ -1,43 +1,44 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xml:id="installing-openstack-dashboard" 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">
<title>Installing the OpenStack Dashboard</title>
<para>Here are the overall steps for creating the OpenStack
dashboard. Details about deployment are available at <link xlink:href="http://docs.openstack.org/developer/horizon/topics/deployment.html">Deploying
Horizon</link>.</para>
<orderedlist>
<listitem>
<para>Install the OpenStack Dashboard framework including Apache and related
modules.</para>
</listitem>
<listitem>
<para>Configure the Dashboard.</para>
</listitem>
<listitem>
<para>Restart and run the Apache server.</para>
</listitem>
</orderedlist>
<para>Install the OpenStack Dashboard, as root:</para>
<title>Install the OpenStack Dashboard</title>
<procedure><title>To install the OpenStack Dashboard:</title><step><para>Install the OpenStack Dashboard as root:</para>
<screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install -y memcached libapache2-mod-wsgi openstack-dashboard</userinput></screen>
<screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install -y memcached python-memcached mod_wsgi openstack-dashboard</userinput></screen>
<para>Next, modify the variable <literal>CACHE_BACKEND</literal> in
<filename os="ubuntu">/etc/openstack-dashboard/local_settings.py</filename><filename os="centos;fedora;rhel">/etc/openstack-dashboard/local_settings</filename> to match the ones set in
<filename os="ubuntu">/etc/memcached.conf</filename><filename os="centos;fedora;rhel">/etc/sysconfig/memcached.conf</filename>. Open
<filename os="ubuntu">/etc/openstack-dashboard/local_settings.py</filename><filename os="centos;fedora;rhel">/etc/openstack-dashboard/local_settings</filename> and look for this
line:</para>
<screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install -y memcached python-memcached mod_wsgi openstack-dashboard</userinput></screen></step>
<step><para>Modify the <literal>CACHE_BACKEND</literal> environment variable
in <filename os="ubuntu"
>/etc/openstack-dashboard/local_settings.py</filename><filename
os="centos;fedora;rhel"
>/etc/openstack-dashboard/local_settings</filename>
to match the ones set in <filename os="ubuntu"
>/etc/memcached.conf</filename><filename
os="centos;fedora;rhel"
>/etc/sysconfig/memcached.conf</filename>.</para><para>Open
<filename os="ubuntu"
>/etc/openstack-dashboard/local_settings.py</filename><filename
os="centos;fedora;rhel"
>/etc/openstack-dashboard/local_settings</filename>
and look for this line:</para>
<programlisting>CACHE_BACKEND = 'memcached://127.0.0.1:11211/'</programlisting>
<note><para>The address and port in the new value need to be equal to
the ones set in <filename os="ubuntu">/etc/memcached.conf</filename><filename os="centos;fedora;rhel">/etc/sysconfig/memcached</filename>.</para></note>
<para>If you change the memcached settings, restart the Apache web
server for the changes to take effect.</para>
<note><para>This guide has selected memcache as a session store for OpenStack Dashboard. There are other
options available, each with benefits and drawbacks. Refer to the OpenStack Dashboard
Session Storage section for more information.</para></note>
<note><para>The address and port must match the ones set in <filename
os="ubuntu"
>/etc/memcached.conf</filename><filename
os="centos;fedora;rhel"
>/etc/sysconfig/memcached</filename>.</para>
<para>If you change the memcached settings, you must restart the Apache web
server for the changes to take effect.</para></note>
<note><para>In this example, memcached is the session store for the OpenStack Dashboard. You can use other options. Each
option has benefits and drawbacks. For more information, see <xref linkend="dashboard-sessions"/>.</para></note>
<para>
<note>
<para>In order to change the timezone you can use either dashboard or inside
<filename os="centos;fedora;rhel">/etc/openstack-dashboard/local_settings</filename><filename os="ubuntu">/etc/openstack-dashboard/local_settings.py</filename> you can
change below mentioned parameter.<programlisting>TIME_ZONE = "UTC"</programlisting>
</para>
<para>To change the timezone, use the dashboard or edit
the <filename os="centos;fedora;rhel"
>/etc/openstack-dashboard/local_settings</filename><filename
os="ubuntu"
>/etc/openstack-dashboard/local_settings.py</filename>
file. </para>
<para>Change the following parameter:
<programlisting>TIME_ZONE = "UTC"</programlisting>
</para>
</note>
</para>
</para></step></procedure>
</section>

0 comments on commit f7593c4

Please sign in to comment.