Add sample configuration files for mod_wsgi

These files really only work for a devstack setup,
but the demonstrate what one would need to do in
a real deployment behind mod_wsgi.

Change-Id: If60ce2aa0b89c055ccc0411aece28042b14ab633
Signed-off-by: Doug Hellmann <doug.hellmann@dreamhost.com>

ceilometer/api/app.wsgi

@@ -0,0 +1,30 @@
+# -*- mode: python -*-
+# -*- encoding: utf-8 -*-
+#
+# Copyright © 2013 New Dream Network, LLC (DreamHost)
+#
+# Author: Doug Hellmann <doug.hellmann@dreamhost.com>
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+"""Use this file for deploying the API under mod_wsgi.
+
+See http://pecan.readthedocs.org/en/latest/deployment.html for details.
+"""
+
+from ceilometer import service
+from ceilometer.api import app
+
+# Initialize the oslo configuration library and logging
+service.prepare_service([])
+
+application = app.VersionSelectorApplication()

doc/source/index.rst

@@ -48,7 +48,7 @@ Table of contents
 
    architecture
    measurements
-   install
+   install/index
    configuration
    webapi/index
    contributing/index

doc/source/install/development.rst

@@ -0,0 +1,54 @@
+..
+      Copyright 2012 Nicolas Barcet for Canonical
+                2013 New Dream Network, LLC (DreamHost)
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+================================================
+ Installing and Running the Development Version
+================================================
+
+Ceilometer has four daemons. The :term:`compute agent` runs on the
+Nova compute node(s) while the :term:`central agent` and
+:term:`collector` run on the cloud's management node(s). In a
+development environment created by devstack_, these two are typically
+the same server. They do not have to be, though, so some of the
+instructions below are duplicated. Skip the steps you have already
+done.
+
+.. _devstack: http://www.devstack.org/
+
+Configuring Devstack
+====================
+
+.. index::
+   double: installing; devstack
+
+1. Create a ``localrc`` file as input to devstack.
+
+2. Ceilometer makes extensive use of the messaging bus, but has not
+   yet been tested with ZeroMQ. We recommend using Rabbit or qpid for
+   now.
+
+3. Nova does not generate the periodic notifications for all known
+   instances by default. To enable these auditing events, set
+   ``instance_usage_audit`` to true in the nova configuration file.
+
+4. The ceilometer services are not enabled by default, so they must be
+   enabled in ``localrc`` before running ``stack.sh``.
+
+This example ``localrc`` file shows all of the settings required for
+ceilometer::
+
+   # Enable the ceilometer services
+   enable_service ceilometer-acompute,ceilometer-acentral,ceilometer-collector,ceilometer-api

doc/source/install/index.rst

@@ -0,0 +1,28 @@
+..
+      Copyright 2013 New Dream Network, LLC (DreamHost)
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _install:
+
+=======================
+ Installing Ceilometer
+=======================
+
+.. toctree::
+   :maxdepth: 2
+
+   development
+   manual
+   mod_wsgi
+

doc/source/install/manual.rst

@@ -1,5 +1,6 @@
 ..
       Copyright 2012 Nicolas Barcet for Canonical
+                2013 New Dream Network, LLC (DreamHost)
 
       Licensed under the Apache License, Version 2.0 (the "License"); you may
       not use this file except in compliance with the License. You may obtain
@@ -13,52 +14,9 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-.. _install:
+=====================
-
+ Installing Manually
-=======
+=====================
-Install
-=======
-
-Installing and Running the Development Version
-++++++++++++++++++++++++++++++++++++++++++++++
-
-Ceilometer has four daemons. The :term:`compute agent` runs on the
-Nova compute node(s) while the :term:`central agent` and
-:term:`collector` run on the cloud's management node(s). In a
-development environment created by devstack_, these two are typically
-the same server. They do not have to be, though, so some of the
-instructions below are duplicated. Skip the steps you have already
-done.
-
-.. _devstack: http://www.devstack.org/
-
-Configuring Devstack
-====================
-
-.. index::
-   double: installing; devstack
-
-1. Create a ``localrc`` file as input to devstack.
-
-2. Ceilometer makes extensive use of the messaging bus, but has not
-   yet been tested with ZeroMQ. We recommend using Rabbit or qpid for
-   now.
-
-3. Nova does not generate the periodic notifications for all known
-   instances by default. To enable these auditing events, set
-   ``instance_usage_audit`` to true in the nova configuration file.
-
-4. The ceilometer services are not enabled by default, so they must be
-   enabled in ``localrc`` before running ``stack.sh``.
-
-This example ``localrc`` file shows all of the settings required for
-ceilometer::
-
-   # Enable the ceilometer services
-   enable_service ceilometer-acompute,ceilometer-acentral,ceilometer-collector,ceilometer-api
-
-Installing Manually
-+++++++++++++++++++
 
 Installing the Collector
 ========================

doc/source/install/mod_wsgi.rst

@@ -0,0 +1,56 @@
+..
+      Copyright 2013 New Dream Network, LLC (DreamHost)
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+====================================
+ Installing the API Behind mod_wsgi
+====================================
+
+Ceilometer comes with a few example files for configuring the API
+service to run behind Apache with ``mod_wsgi``.
+
+app.wsgi
+========
+
+The file ``ceilometer/api/app.wsgi`` sets up the V2 API WSGI
+application. The file is installed with the rest of the ceilometer
+application code, and should not need to be modified.
+
+etc/apache2/ceilometer
+======================
+
+The ``etc/apache2/ceilometer`` file contains example settings that
+work with a copy of ceilometer installed via devstack.
+
+.. literalinclude:: ../../../etc/apache2/ceilometer
+
+1. Copy or symlink the file to ``/etc/apache2/sites-avilable``.
+
+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.
+
+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.
+
+   ::
+
+      $ a2ensite ceilometer
+      $ service apache2 reload

etc/apache2/ceilometer

@@ -0,0 +1,33 @@
+# Copyright (c) 2013 New Dream Network, LLC (DreamHost)
+#
+# Author: Doug Hellmann <doug.hellmann@dreamhost.com>
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# 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.
+
+<VirtualHost *>
+    WSGIDaemonProcess ceilometer user=vagrant group=vagrant threads=5
+    WSGIScriptAlias / /opt/stack/ceilometer/ceilometer/api/app.wsgi
+
+    SetEnv APACHE_RUN_USER vagrant
+    SetEnv APACHE_RUN_GROUP vagrant
+    WSGIProcessGroup ceilometer
+
+    ErrorLog /var/log/apache2/ceilometer_error.log
+    LogLevel warn
+    CustomLog /var/log/apache2/ceilometer_access.log combined
+
+</VirtualHost>