docs/main/HelloWorld.rst | 6
docs/main/IntegratingWithTG2.rst | 199 ++++++++++++---------------
docs/main/MokshaHub.rst | 6
docs/main/PluginEntryPoints.rst | 40 ++++-
docs/main/RPMInstallation.rst | 66 +++-----
docs/main/Security.rst | 9 +
docs/main/UsingLiveSocketOutsideOfMoksha.rst | 15 +-
docs/main/VirtualenvInstallation.rst | 10 +
8 files changed, 188 insertions(+), 163 deletions(-)
New commits:
commit aa6d45b6c07701b97f07312ebea4f1536f4cc2d3
Author: Luke Macken <lmacken(a)redhat.com>
Date: Mon Dec 20 19:06:51 2010 -0500
A ton of documentation improvements...
diff --git a/docs/main/HelloWorld.rst b/docs/main/HelloWorld.rst
index 19c058a..7372a1b 100644
--- a/docs/main/HelloWorld.rst
+++ b/docs/main/HelloWorld.rst
@@ -6,7 +6,11 @@ The goal of this tutorial is to show the simplicity of Moksha's API
by creating
basic "Hello World" components in one demo.
:Download:
https://fedorahosted.org/releases/m/o/moksha/moksha-helloworld.tar.bz2
-:Demo Source:
https://fedorahosted.org/moksha/browser/moksha/apps/helloworld
+:Browse Source:
https://fedorahosted.org/moksha/browser/moksha/apps/helloworld
+
+.. note::
+
+ You can easily run this demo by extracting the above tarball, and running ``moksha
start`` within it.
The Controller
--------------
diff --git a/docs/main/IntegratingWithTG2.rst b/docs/main/IntegratingWithTG2.rst
index b7c0d30..5eaff7a 100644
--- a/docs/main/IntegratingWithTG2.rst
+++ b/docs/main/IntegratingWithTG2.rst
@@ -7,6 +7,7 @@ The best way to learn how to use Moksha within TurboGears2 by example.
.. image:: ../_static/jqplotdemo.png
:Running demo:
http://moksha.csh.rit.edu/apps/jqplotdemo
+:Source code:
http://lmacken.fedorapeople.org/JQPlotDemo-0.1dev.tar.gz
We'll take a demo written to show off the :mod:`tw.jquery.jqplot` module for
example. This demo shows off the JQPlotWidget, which queries the server every
@@ -16,9 +17,6 @@ Porting this app to use Moksha's LiveWidget would allow us to create
a much
more efficient version of this demo, as it would receive data from the server
asynchronously, instead of polling for it.
-The source code for the original JQPlotDemo can be found here:
-http://lmacken.fedorapeople.org/JQPlotDemo-0.1dev.tar.gz
-
Now we'll go over and explain each patch required to utilize Moksha within this
TurboGears2 application.
@@ -213,106 +211,99 @@ all of the widgets can share.
)
-.. note::
-
- The source code for the MokshaJQPlotDemo can be found here:
-
-
http://lmacken.fedorapeople.org/MokshaJQPlotDemo.tar.bz2
-
-
-At this point, you're all set to run `paster serve development.ini` and enjoy
+At this point, you're all set to run ``paster serve development.ini`` and enjoy
your shiny new live web app.
-You are now free to go and deploy your application however you please.
-However, Moksha can run it for you if you wish...
-
---------------------------------------------------------------------------------
-
-Running your app inside of Moksha
----------------------------------
-
-The above example shows how you can easily use Moksha within your existing app.
-Moksha also allows lets you run your app inside of it. Moksha is preconfigured
-to run in an Apache & mod_wsgi environment, which will handle loading and
-mounting your apps within itself.
-
-
-.. warning::
-
- If you're running your app inside of Moksha, you must ensure that you
- are not running the MokshaMiddleware inside of your app first. This
- currently leads to a fun infinite WSGI middleware loop :)
-
- So if you're creating a new app, don't worry about this, but for the above
- example, just remove the `wrap_app=make_moksha_middleware` from your
- `jqplotdemo/config/middleware.py`
-
-
-Create your WSGI app
-~~~~~~~~~~~~~~~~~~~~
-
-If your app is already WSGI-mountable, then don't worry about this. For a
TurboGears2 app, it's as easy as:
-
-.. code-block:: diff
-
- --- /dev/null
- +++ b/jqplotdemo/wsgi.py
- @@ -0,0 +1,2 @@
- +from paste.deploy import loadapp
- +application = loadapp('config:/etc/moksha/conf.d/jqplotdemo/production.ini')
-
-
-Make a production configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In production we want to make sure any caches are setup in the right spot.
-We base the `production.ini` on our existing `development.ini`, and make a tiny tweak.
-
-.. code-block:: diff
-
- --- development.ini
- +++ production.in
- @@ -23,7 +23,7 @@
- use = egg:JQPlotDemo
- lang = en
- -cache_dir = %(here)s/data
- +cache_dir = /var/cache/moksha/jqplotdemo/data
- beaker.session.key = jqplotdemo
-
-.. code-block:: diff
-
- --- a/ MANIFEST.in
- +++ b/ MANIFEST.in
- @@ -2,3 +2,4 @@ recursive-include jqplotdemo/public *
- include jqplotdemo/public/favicon.ico
- recursive-include jqplotdemo/i18n *
- recursive-include jqplotdemo/templates *
- +include production.ini
-
-
-Integrate your TG2/WSGI app into Moksha
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can plug your WSGI application into Moksha by using the `moksha.wsgiapp`
-entry-point.
-
-.. code-block:: diff
-
- --- a/ setup.py
- +++ b/ setup.py
- @@ -47,6 +47,9 @@ setup(
- [moksha.stream]
- jqplot_stream = jqplotdemo.streams:JQPlotDemoStream
-
- + [moksha.wsgiapp]
- + jqplotdemo = jqplotdemo.wsgi:application
- +
- [moksha.global]
- moksha_socket = moksha.api.widgets:moksha_socket
-
-
-.. seealso::
-
- :doc:`PluginEntryPoints`
-
-
+To start the message producing data stream, you will need to run the ``moksha-hub``.
+
+
+.. --------------------------------------------------------------------------------
+
+ Running your app inside of Moksha
+ ---------------------------------
+
+ The above example shows how you can easily use Moksha within your existing app.
+ Moksha also allows lets you run your app inside of it. Moksha is preconfigured
+ to run in an Apache & mod_wsgi environment, which will handle loading and
+ mounting your apps within itself.
+
+
+ .. warning::
+
+ If you're running your app inside of Moksha, you must ensure that you
+ are not running the MokshaMiddleware inside of your app first. This
+ currently leads to a fun infinite WSGI middleware loop :)
+
+ So if you're creating a new app, don't worry about this, but for the above
+ example, just remove the `wrap_app=make_moksha_middleware` from your
+ `jqplotdemo/config/middleware.py`
+
+
+ Create your WSGI app
+ ~~~~~~~~~~~~~~~~~~~~
+
+ If your app is already WSGI-mountable, then don't worry about this. For a
TurboGears2 app, it's as easy as:
+
+ .. code-block:: diff
+
+ --- /dev/null
+ +++ b/jqplotdemo/wsgi.py
+ @@ -0,0 +1,2 @@
+ +from paste.deploy import loadapp
+ +application =
loadapp('config:/etc/moksha/conf.d/jqplotdemo/production.ini')
+
+
+ Make a production configuration
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ In production we want to make sure any caches are setup in the right spot.
+ We base the `production.ini` on our existing `development.ini`, and make a tiny
tweak.
+
+ .. code-block:: diff
+
+ --- development.ini
+ +++ production.in
+ @@ -23,7 +23,7 @@
+ use = egg:JQPlotDemo
+ lang = en
+ -cache_dir = %(here)s/data
+ +cache_dir = /var/cache/moksha/jqplotdemo/data
+ beaker.session.key = jqplotdemo
+
+ .. code-block:: diff
+
+ --- a/ MANIFEST.in
+ +++ b/ MANIFEST.in
+ @@ -2,3 +2,4 @@ recursive-include jqplotdemo/public *
+ include jqplotdemo/public/favicon.ico
+ recursive-include jqplotdemo/i18n *
+ recursive-include jqplotdemo/templates *
+ +include production.ini
+
+
+ Integrate your TG2/WSGI app into Moksha
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ You can plug your WSGI application into Moksha by using the `moksha.wsgiapp`
+ entry-point.
+
+ .. code-block:: diff
+
+ --- a/ setup.py
+ +++ b/ setup.py
+ @@ -47,6 +47,9 @@ setup(
+ [moksha.stream]
+ jqplot_stream = jqplotdemo.streams:JQPlotDemoStream
+
+ + [moksha.wsgiapp]
+ + jqplotdemo = jqplotdemo.wsgi:application
+ +
+ [moksha.global]
+ moksha_socket = moksha.api.widgets:moksha_socket
+
+
+ .. seealso::
+
+ :doc:`PluginEntryPoints`
+
+
diff --git a/docs/main/MokshaHub.rst b/docs/main/MokshaHub.rst
index 1886cb3..1003e71 100644
--- a/docs/main/MokshaHub.rst
+++ b/docs/main/MokshaHub.rst
@@ -19,15 +19,15 @@ applications to send messages to a given topic.
Behind the scenes, the :class:`MokshaHub` will automatically connect up to
whatever message brokers are configured, and create a new session. The
:meth:`send_message` method will automatically handle encoding your message to
-JSON (unless you pass `jsonify=False`), and sending it to the appropriate
+JSON (unless you pass ``jsonify=False``), and sending it to the appropriate
message broker.
CentralMokshaHub
----------------
-The :class:`CentralMokshaHub` is the primary consumer of all message `topics`.
+The :class:`CentralMokshaHub` is the primary consumer of all message ``topics``.
It runs outside of the Moksha WSGI application stack, and is automatically
-started by the `start-moksha` script (and can be started manually by running
`moksha-hub`.
+started by the ``start-moksha`` script (and can be started manually by running
``moksha-hub``).
The :class:`CentralMokshaHub` currently handles the following tasks:
diff --git a/docs/main/PluginEntryPoints.rst b/docs/main/PluginEntryPoints.rst
index 210e0b0..17b2e1b 100644
--- a/docs/main/PluginEntryPoints.rst
+++ b/docs/main/PluginEntryPoints.rst
@@ -7,18 +7,24 @@ and store them in ``moksha.apps`` and ``moksha._widgets`` dictionaries.
These can then be accessed at any time by any application or widget during
any request.
-Mounting a WSGI application
----------------------------
+What is an Entry Point?
+-----------------------
-You can mount an existing WSGI application by pointing to it
-in the ``setup.py`` on the ``[moksha.wsgiapp]`` entry-point.
+Entry points are a Python setuptools/distribute feature that allows packages to
+register something under a specific key that other packages can query for.
+This is how you make Moksha aware of your widgets/apps/producers/consumers.
+
+Entry points are defined in your projects ``setup.py`` like so:
.. code-block:: python
- [moksha.wsgiapp]
- mywsgiapp = mywsgiapp.wsgiapp:MyWSGIApplication
+ setup(name='moksha.helloworld',
+ ...
+ entry_points="""
+ [moksha.widget]
+ hellowidget = helloworld.widgets:HelloWorldWidget
+ """
-Your WSGI application will then be accessable via ``/apps/mywsgiapp`` in Moksha.
Mounting a TurboGears application
----------------------------------
@@ -48,6 +54,26 @@ You can plug an existing ToscaWidget into Moksha by adding it to the
``[moksha.w
Your Widget will then be accessable via ``/widgets/mywidget`` in Moksha.
+Mounting a WSGI application
+---------------------------
+
+You can mount an existing WSGI application by pointing to it
+in the ``setup.py`` on the ``[moksha.wsgiapp]`` entry-point.
+
+.. code-block:: python
+
+ [moksha.wsgiapp]
+ mywsgiapp = mywsgiapp.wsgiapp:MyWSGIApplication
+
+Your WSGI application will then be accessable via ``/apps/mywsgiapp`` in Moksha.
+
+.. warning::
+
+ At the moment it is not recommened that you mount a TurboGears/Pylons app as
+ a WSGI application inside of Moksha, since the ``pylons.config`` objects
+ will conflict. This issue will be addressed in the future. Instead, you can
+ simply mount a Controller as a ``moksha.application``.
+
Configuration
-------------
diff --git a/docs/main/RPMInstallation.rst b/docs/main/RPMInstallation.rst
index 6f004eb..7903970 100644
--- a/docs/main/RPMInstallation.rst
+++ b/docs/main/RPMInstallation.rst
@@ -2,41 +2,6 @@
Setting up a Moksha RPM & mod_wsgi environment
==============================================
-Setup the TurboGears2/Moksha yum repo
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-At the moment, all of Moksha's dependencies are not all in Fedora. They are
-all currently under review, but in the mean time these instructions will run
-Moksha within a virtual Python environment, without changing your global
-site-packages.
-
-You can track the progress of getting TurboGears2 into Fedora `here
<
http://fedoraproject.org/wiki/TurboGears2>`_.
-
-To setup Luke Macken's TurboGears2 yum repository, run the following commands
-as root, replacing `$DISTRO` with either `fedora-rawhide`, `fedora-11`,
-`fedora-10`, or `epel-5`.
-
-.. code-block:: bash
-
- cd /etc/yum.repos.d/
- curl -O
http://lmacken.fedorapeople.org/rpms/tg2/$DISTRO/tg2.repo
- yum -y install TurboGears2 python-tg-devtools
-
-.. note::
-
- It is recommended that you perform a `yum update` after installing
- the Moksha/TurboGears2 stack, to ensure that you have the latest
- versions of all the dependencies.
-
-.. note::
-
- At the moment the full TurboGears2 stack is not yet fully in
- Fedora/EPEL, so you'll have to hook up a third party repository. You
- can track the status of TurboGears2 in Fedora here:
-
-
http://fedoraproject.org/wiki/TurboGears2
-
-
Installing the Moksha Apache/mod_wsgi server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -60,9 +25,29 @@ Running Moksha
Running Orbited
~~~~~~~~~~~~~~~
+Out of the box Orbited comes with a very minimal configuration
+
+Copy over Moksha's Orbited configuration:
+
+.. code-block:: bash
+
+ # cp /etc/moksha/orbited.cfg /etc/orbited.cfg
+
+.. note::
+
+ Moksha's Orbited configuration enables the MorbidQ STOMP message broker by
default,
+ for ease of development. This can be disabled by commenting out the line
``stomp://:61613``
+ and the line under the ``[access]`` section.
+
+Starting the Orbited daemon
+
.. code-block:: bash
- $ orbited -c /etc/moksha/orbited.cfg
+ # service orbited start
+
+.. note::
+
+ You can also start orbited by hand by running ``orbited -c /etc/moksha/orbited.cfg``
Running the Moksha Hub
@@ -70,7 +55,7 @@ Running the Moksha Hub
.. code-block:: bash
- $ sudo /sbin/service moksha-hub restart
+ # service moksha-hub start
Install the dependencies and setup your RPM tree
@@ -85,9 +70,10 @@ This step is only necessary if you plan on building moksha apps.
$ sudo yum-builddep -y moksha
-Watching the Error Log
-~~~~~~~~~~~~~~~~~~~~~~
+Watching the logs
+~~~~~~~~~~~~~~~~~
.. code-block:: bash
- $ sudo tail -f /var/log/httpd/moksha_error_log
+ # tail -f /var/log/httpd/moksha_{access,error}_log
+ # tail -f /var/log/moksha/moksha-hub.log
diff --git a/docs/main/Security.rst b/docs/main/Security.rst
index af6eb12..0932a74 100644
--- a/docs/main/Security.rst
+++ b/docs/main/Security.rst
@@ -4,10 +4,17 @@ Security
Cross-site Request Forgery Protection
-------------------------------------
-Moksha offers CSRF protection for authenticated users by default.
+Moksha offers a layer of CSRF protection for authenticated users.
For more information on `CSRF`, see the `Wikipedia entry
<
http://en.wikipedia.org/wiki/Cross-site_request_forgery>`_
+You can enable/disable this middleware by using the following configuration
+option in your ``production.ini`` file:
+
+.. code-block:: python
+
+ moksha.csrf_protection = True
+
WSGI Middleware
~~~~~~~~~~~~~~~
diff --git a/docs/main/UsingLiveSocketOutsideOfMoksha.rst
b/docs/main/UsingLiveSocketOutsideOfMoksha.rst
index 37dc9ed..daa193c 100644
--- a/docs/main/UsingLiveSocketOutsideOfMoksha.rst
+++ b/docs/main/UsingLiveSocketOutsideOfMoksha.rst
@@ -7,9 +7,12 @@ have to learn Python or TurboGears?
Thankfully, Moksha allows you to leverage it's realtime pipes on any existing
web page without having to write a line of Python code.
-Add code snippet to your web page
-Configure your message broker
-Start Moksha
+This means that you can have your web site listen to topics from your message
+broker, and run javascript when new messages arrive.
+
+All you need to do is add a single ``<script>`` tag to your web site that
+specifies the topic that you wish to listen to, and the javascript function
+that should be called with each new message as they arrive.
.. code-block:: html
@@ -28,7 +31,7 @@ Start Moksha
<script type="text/javascript"
src="http://localhost:8080/livesocket?topic=helloworld&callback=consume_message"></script>
</html>
-Caveats
--------
+.. note::
-Must be under the same domain name.
+ In order for the live sockets to work properly, Moksha (specifically Orbited) must be
running
+ under the same domain as your web site.
diff --git a/docs/main/VirtualenvInstallation.rst b/docs/main/VirtualenvInstallation.rst
index 7d9d282..23b9fdb 100644
--- a/docs/main/VirtualenvInstallation.rst
+++ b/docs/main/VirtualenvInstallation.rst
@@ -3,7 +3,7 @@ Virtualenv installation
This guide will help quickly get you up and running with a local copy of
Moksha. It will run the Moksha WSGI application using the Paste threaded http
-server, a single orbited daemon with an embeded MorbidQ stomp message broker,
+server, a single Orbited socket-proxy daemon with an embeded MorbidQ stomp message
broker,
SQLite SQLAlchemy and Feed databases, and an in-memory cache. This setup is
meant to be dead-simple to get up and running, and is not designed for
production deployments.
@@ -16,11 +16,19 @@ Installing the necessary dependencies
You'll need the `virtualenv <
http://pypi.python.org/pypi/virtualenv>`_
package.
+For Fedora/Red Hat/CentOS based environments:
+
.. code-block:: bash
# yum -y install python-virtualenv gcc openssl-devel
# yum-builddep -y python-lxml pyOpenSSL python-sqlite2
+On Ubuntu/Debian:
+
+.. code-block:: bash
+
+ # apt-get install git python-dev python-virtualenv
+
Getting the code
~~~~~~~~~~~~~~~~