DOCS: update to deployment documentation and new production deployments doc

docs/source/deploying.rst

@@ -244,7 +244,7 @@ Production MediaGoblin Deployments with Paste
 
 The instance configured with ``lazyserver`` is not ideal for a
 production MediaGoblin deployment. Ideally, you should be able to use
-a a control script (i.e. init script.) to launch and restart the
+a control script (i.e. init script.) to launch and restart the
 MediaGoblin process.
 
 Use the following command as the basis for such a script: ::
@@ -252,13 +252,13 @@ Use the following command as the basis for such a script: ::
        CELERY_ALWAYS_EAGER=true \
         /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
         /srv/mediagoblin.example.org/mediagoblin/paste.ini \
-        --pid-file=/tmp/mediagoblin.pid \
+        --pid-file=/var/run/mediagoblin.pid \
         --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 \
 
 .. note::
 
    The above configuration places MediaGoblin in "always eager" mode
    with Celery. This is fine for development and smaller
-   deployments. However, if you're getting into the really large
-   deployment category, consider reading the section of this manual on
-   Celery.
+   deployments. However, for larger production deployments with larger
+   processing requirements, see the ":doc:`production-deployments`"
+   documentation.

docs/source/production-deployments.rst

@@ -0,0 +1,48 @@
+=========================================
+Considerations for Production Deployments
+=========================================
+
+This document contains a number of suggestions for deploying
+MediaGoblin in actual production environments. Consider
+":doc:`deploying`" for a basic overview of how to deploy Media
+Goblin.
+
+Celery
+------
+
+While the ``./lazyserer.sh`` configuration provides an efficient way to
+start using a MediaGoblin instance, it is not suitable for production
+deployments for several reasons:
+
+1. In nearly every scenario, work on the Celery queue will need to
+   balance with the demands of other processes, and cannot proceed
+   synchronously. This is a particularly relevant problem if you use
+   MediaGoblin to host Video content.
+
+2. Processing with Celery ought to be operationally separate from the
+   MediaGoblin application itself, this simplifies management and
+   support better workload distribution.
+
+3. ... additional reason here. ....
+
+Build an :ref:`init script <init-script>` around the following
+command.
+
+      CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd
+
+Modify your existing MediaGoblin and application init scripts, if
+necessary, to prevent them from starting their own ``celeryd``
+processes.
+
+.. _init-script:
+
+Use an Init Script
+-------------------
+
+TODO insert init script here
+
+Other Concerns
+--------------
+
+TODO What are they?
+