Merge "Improve ceilometer-api install documentation"

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