Improve ceilometer-api install documentation

This updates the mod_wsgi configuration and installation information
to be more in line with current usage. It also makes the
recommendation to use mod_wsgi more strongly than has been made in
the past. In general we don't want people to be running
ceilometer-api at all, but it is good for them to have the option.

Also an effort has been made to clarify the difference between rpm
and deb installations of Apache.

DocImpact

Change-Id: I11f92d91f4bdea884c266b91b52f9d012abd33b9
Partially-Implements: blueprint remove-web-eventlet

doc/source/install/manual.rst

@@ -524,9 +524,18 @@ Installing the API Server
 
 .. _documentation: http://pythonpaste.org/deploy/
 
-6. Start the API server.
+6. Choose and start the API server.
 
-   ::
+   Ceilometer includes the ``ceilometer-api`` command. This can be
+   used to run the API server. For smaller or proof-of-concept
+   installations this is a reasonable choice. For larger installations it
+   is strongly recommended to install the API server in a WSGI host
+   such as mod_wsgi (see :doc:`mod_wsgi`). Doing so will provide better
+   performance and more options for making adjustments specific to the
+   installation environment.
+
+   If you are using the ``ceilometer-api`` command it can be started
+   as::
 
     $ ceilometer-api
 

doc/source/install/mod_wsgi.rst

@@ -35,26 +35,24 @@ work with a copy of ceilometer installed via devstack.
 
 .. literalinclude:: ../../../etc/apache2/ceilometer
 
-1. Copy or symlink the file to ``/etc/apache2/sites-available``.
+1. On deb-based systems copy or symlink the file to
+   ``/etc/apache2/sites-available``. For rpm-based systems the file will go in
+   ``/etc/httpd/conf.d``.
 
-2. Modify the ``VirtualHost`` directive, setting a hostname or IP for
+2. Modify the ``WSGIDaemonProcess`` directive to set the ``user`` and
-   the service. The default settings assume that the ceilometer API is
+   ``group`` values to a appropriate user on your server. In many
-   the only service running on the local Apache instance, which
+   installations ``ceilometer`` will be correct.
-   conflicts with Horizon's default configuration.
 
-3. Modify the ``WSGIDaemonProcess`` directive to set the
+3. Enable the ceilometer site. On deb-based systems::
-   ``user`` and ``group`` values to a user available on your server.
-
-4. Modify the ``APACHE_RUN_USER`` and ``APACHE_RUN_GROUP`` values to
-   the name of a user and group available on your server.
-
-5. Enable the ceilometer site.
-
-   ::
 
       $ a2ensite ceilometer
       $ service apache2 reload
 
+   On rpm-based systems::
+
+      $ service httpd reload
+
+
 Limitation
 ==========
 

etc/apache2/ceilometer

@@ -13,19 +13,27 @@
 # under the License.
 
 # This is an example Apache2 configuration file for using the
-# ceilometer API through mod_wsgi.  This version assumes you are
+# ceilometer API through mod_wsgi.
-# running devstack to configure the software.
 
-<VirtualHost *>
+# Note: If you are using a Debian-based system then the paths
-    WSGIDaemonProcess ceilometer-api user=vagrant group=vagrant processes=2 threads=10
+# "/var/log/httpd" and "/var/run/httpd" will use "apache2" instead
-    WSGIScriptAlias / /opt/stack/ceilometer/ceilometer/api/app.wsgi
+# of "httpd".
+#
+# The number of processes and threads is an example only and should
+# be adjusted according to local requirements.
 
-    SetEnv APACHE_RUN_USER vagrant
+Listen 8777
-    SetEnv APACHE_RUN_GROUP vagrant
+
+<VirtualHost *:8777>
+    WSGIDaemonProcess ceilometer-api processes=2 threads=10 user=SOMEUSER display-name=%{GROUP}
     WSGIProcessGroup ceilometer-api
-
+    WSGIScriptAlias / /var/www/ceilometer/app
-    ErrorLog /var/log/apache2/ceilometer_error.log
+    WSGIApplicationGroup %{GLOBAL}
-    LogLevel warn
+    <IfVersion >= 2.4>
-    CustomLog /var/log/apache2/ceilometer_access.log combined
+        ErrorLogFormat "%{cu}t %M"
-
+    </IfVersion>
+    ErrorLog /var/log/httpd/ceilometer_error.log
+    CustomLog /var/log/httpd/ceilometer_access.log combined
 </VirtualHost>
+
+WSGISocketPrefix /var/run/httpd