docs: Added systemd info. Reworked init script info.

Added tested systemd service files. Modified the structure of the
section about init scripts.

docs/source/siteadmin/production-deployments.rst

@@ -19,15 +19,139 @@ 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 MediaGoblin.
 
-Deploy with Paste
+Deploy with paste
 -----------------
 
 The MediaGoblin WSGI application instance you get with ``./lazyserver.sh`` is
 not ideal for a production MediaGoblin deployment. Ideally, you should be able
-to use an "init" or "control" script to launch and restart the MediaGoblin
+to use a systemd "service file" or an "init script" to launch and restart the
-process.
+MediaGoblin process.
 
-Use the following command as the basis for such a script:
+We will explore setting up MediaGoblin systemd service files or init scripts,
+but first we need to create the directory that will store the logs that result
+from the MediaGoblin-related process.
+
+.. _create-log-file-dir:
+
+Create the directory for your log file:
+---------------------------------------
+
+Production logs for the MediaGoblin application are kept in the
+``/var/log/mediagoblin`` directory.  Create the directory and give it the
+proper permissions::
+
+    sudo mkdir -p /var/log/mediagoblin && sudo chown -hR mediagoblin:mediagoblin /var/log/mediagoblin
+
+
+.. _systemd-service-files:
+
+Use systemd service files
+-------------------------
+
+If your operating system uses systemd, you can use systemd ``service files``
+to manage both the Celery and Paste processes. Place the following service
+files in the ``/etc/systemd/system/`` directory.
+
+The first file should be named ``mediagoblin-celeryd.service". Be sure to
+modify it to suit your environment's setup:
+
+.. code-block:: bash
+
+    # Set the WorkingDirectory, Environment and ExecStart values to match your environment.
+    # If using Debian/Ubuntu, mkdir and chown are located in /bin/mkdir and /bin/chown, respectively.
+    # If using Fedora/CentOS/Red Hat, mkdir and chown are located in /usr/bin/mkdir and /usr/bin/chown, respectively.
+
+    [Unit]
+    Description=Mediagoblin Celeryd
+
+    [Service]
+    User=mediagoblin
+    Group=mediagoblin
+    Type=simple
+    WorkingDirectory=/srv/mediagoblin.example.org/mediagoblin
+    # Create directory for PID (if needed) and set ownership
+    ExecStartPre=/usr/bin/mkdir -p /run/mediagoblin
+    ExecStartPre=/usr/bin/chown -hR mediagoblin:mediagoblin /run/mediagoblin
+    # Celery process will run as the `mediagoblin` user ater start.
+    Environment=MEDIAGOBLIN_CONFIG=/srv/mediagoblin.example.org/mediagoblin/mediagoblin_local.ini \
+                CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery
+    ExecStart=/srv/mediagoblin.example.org/mediagoblin/bin/celery worker \
+                  --logfile=/var/log/mediagoblin/celery.log \
+                  --loglevel=INFO
+    PIDFile=/run/mediagoblin/mediagoblin-celeryd.pid
+    
+    [Install]
+    WantedBy=multi-user.target
+
+
+The second file should be named ``mediagoblin-paster.service":
+
+.. code-block:: bash
+
+    # Set the WorkingDirectory, Environment and ExecStart values to match your environment.
+    # If using Debian/Ubuntu, mkdir and chown are located in /bin/mkdir and /bin/chown, respectively.
+    # If using Fedora/CentOS/Red Hat, mkdir and chown are located in /usr/bin/mkdir and /usr/bin/chown, respectively.
+    [Unit]
+    Description=Mediagoblin
+    
+    [Service]
+    Type=forking
+    User=mediagoblin
+    Group=mediagoblin
+    Environment=CELERY_ALWAYS_EAGER=false
+    WorkingDirectory=/srv/mediagoblin.example.org/mediagoblin
+    # Start mg-paster process as root, then switch to mediagoblin user/group
+    PermissionsStartOnly=true
+    ExecStartPre=-/usr/bin/mkdir -p /var/run/mediagoblin
+    ExecStartPre=/usr/bin/chown -R mediagoblin:mediagoblin /var/run/mediagoblin/
+    
+    ExecStart=/srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
+                  /srv/mediagoblin.example.org/mediagoblin/paste_local.ini \
+                  --pid-file=/var/run/mediagoblin/mediagoblin.pid \
+                  --log-file=/var/log/mediagoblin/mediagoblin.log \
+                  --daemon \
+                  --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
+    ExecStop=/srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
+                 --pid-file=/var/run/mediagoblin/mediagoblin.pid \
+                 /srv/mediagoblin.example.org/mediagoblin/paste_local.ini stop
+    PIDFile=/var/run/mediagoblin/mediagoblin.pid
+    
+    [Install]
+    WantedBy=multi-user.target
+
+
+Enable these processes to start at boot by entering::
+
+    sudo systemctl enable mediagoblin-celeryd.service && sudo systemctl enable mediagoblin-paster.service
+
+
+Start the processes for the current session with:
+
+    sudo systemctl start mediagoblin-celeryd.service && sudo systemctl start mediagoblin-paster.service
+
+
+If either command above gives you an error, you can investigate the cause of
+the error by entering::
+
+    sudo systemctl status mediagoblin-celeryd.service  or
+    sudo systemctl status mediagoblin-paster.service
+
+The above ``systemctl status`` command is also useful if you ever want to
+confirm that a process is still running. If you make any changes to the service
+files, you can reload the service files by entering:
+
+    sudo systemctl daemon-reload
+
+After entering that command, you can attempt to start the Celery or Paste
+processes again.
+
+.. _init-script:
+
+Use an init script
+------------------
+
+If your system does not use systemd, you can use the following command as the
+basis for an init script:
 
 .. code-block:: bash
 
@@ -53,7 +177,30 @@ as the basis for your script:
      --pid-file=/var/run/mediagoblin.pid \
      --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
 
-Separate Celery
+
+Members of the MediaGoblin community have provided init scripts for the
+following GNU/Linux distributions:
+
+Debian
+  * `GNU MediaGoblin init scripts
+    <https://github.com/joar/mediagoblin-init-scripts>`_
+    by `Joar Wandborg <http://wandborg.se>`_
+
+Arch Linux
+  * `MediaGoblin - ArchLinux rc.d scripts
+    <http://whird.jpope.org/2012/04/14/mediagoblin-archlinux-rcd-scripts>`_
+    by `Jeremy Pope <http://jpope.org/>`_
+  * `Mediagoblin init script on Archlinux
+    <http://chimo.chromic.org/2012/03/01/mediagoblin-init-script-on-archlinux/>`_
+    by `Chimo <http://chimo.chromic.org/>`_
+
+You can reference these scripts to create an init script for your own operating
+system. Similar scripts will be in your system's ``/etc/init.d/``
+or ``/etc/rc.d/`` directory, but the specifics of an init script will vary from
+one distribution to the next.
+
+
+Separate celery
 ---------------
 
 MediaGoblin uses `Celery`_ to handle heavy and long-running tasks. Celery can
@@ -91,6 +238,11 @@ To launch Celery separately from the MediaGoblin WSGI application:
 
         CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd
 
+If you use our example systemd ``service files``, Celery will be set to the
+"CELERY_ALWAYS_EAGER=false" value by default. This will provide your users
+with the best user experience, as all media processing will be done in the
+background.
+
 .. _sentry:
 
 Set up sentry to monitor exceptions
@@ -102,31 +254,6 @@ documentation.
 .. _`raven`: http://raven.readthedocs.org
 
 
-.. _init-script:
-
-Use an Init Script
-------------------
-
-Look in your system's ``/etc/init.d/`` or ``/etc/rc.d/`` directory for
-examples of how to build scripts that will start, stop, and restart
-MediaGoblin and Celery. These scripts will vary by
-distribution/operating system.
-
-These are scripts provided by the MediaGoblin community: 
-
-Debian
-  * `GNU MediaGoblin init scripts
-    <https://github.com/joar/mediagoblin-init-scripts>`_
-    by `Joar Wandborg <http://wandborg.se>`_
-
-Arch Linux
-  * `MediaGoblin - ArchLinux rc.d scripts
-    <http://whird.jpope.org/2012/04/14/mediagoblin-archlinux-rcd-scripts>`_
-    by `Jeremy Pope <http://jpope.org/>`_
-  * `Mediagoblin init script on Archlinux
-    <http://chimo.chromic.org/2012/03/01/mediagoblin-init-script-on-archlinux/>`_
-    by `Chimo <http://chimo.chromic.org/>`_
-
 .. TODO insert init script here
 .. TODO are additional concerns ?
    .. Other Concerns