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
-   the service. The default settings assume that the ceilometer API is
-   the only service running on the local Apache instance, which
-   conflicts with Horizon's default configuration.
+2. Modify the ``WSGIDaemonProcess`` directive to set the ``user`` and
+   ``group`` values to a appropriate user on your server. In many
+   installations ``ceilometer`` will be correct.
 
-3. Modify the ``WSGIDaemonProcess`` directive to set the
-   ``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.
-
-   ::
+3. Enable the ceilometer site. On deb-based systems::
 
       $ 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
-# running devstack to configure the software.
+# ceilometer API through mod_wsgi.
 
-<VirtualHost *>
-    WSGIDaemonProcess ceilometer-api user=vagrant group=vagrant processes=2 threads=10
-    WSGIScriptAlias / /opt/stack/ceilometer/ceilometer/api/app.wsgi
+# Note: If you are using a Debian-based system then the paths
+# "/var/log/httpd" and "/var/run/httpd" will use "apache2" instead
+# 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
-    SetEnv APACHE_RUN_GROUP vagrant
+Listen 8777
+
+<VirtualHost *:8777>
+    WSGIDaemonProcess ceilometer-api processes=2 threads=10 user=SOMEUSER display-name=%{GROUP}
     WSGIProcessGroup ceilometer-api
-
-    ErrorLog /var/log/apache2/ceilometer_error.log
-    LogLevel warn
-    CustomLog /var/log/apache2/ceilometer_access.log combined
-
+    WSGIScriptAlias / /var/www/ceilometer/app
+    WSGIApplicationGroup %{GLOBAL}
+    <IfVersion >= 2.4>
+        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