.. MediaGoblin Documentation
- Written in 2011, 2012 by MediaGoblin contributors
+ Written in 2011, 2012, 2013, 2014, 2015 by MediaGoblin contributors
To the extent possible under law, the author(s) have dedicated all
copyright and related and neighboring rights to this software to
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
-process.
+to use a Systemd service file or an init script to launch and restart the
+MediaGoblin process.
-Use the following command as the basis for such a script:
+We will explore setting up MediaGoblin Systemd service files and init scripts,
+but first we need to create the directory that will store the MediaGoblin logs.
+
+
+.. _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/*buntu, 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
+ # Start mg-celeryd process as root, then switch to mediagoblin user/group
+ # (This is needed to run the ExecStartPre commands)
+ PermissionsStartOnly=true
+ # Create directory for PID (if needed) and set ownership
+ ExecStartPre=/bin/mkdir -p /run/mediagoblin
+ ExecStartPre=/bin/chown -hR mediagoblin:mediagoblin /run/mediagoblin
+ # Celery process will run as the `mediagoblin` user after start.
+ Environment=MEDIAGOBLIN_CONFIG=/srv/mediagoblin.example.org/mediagoblin/mediagoblin.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/*buntu, 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=-/bin/mkdir -p /run/mediagoblin
+ ExecStartPre=/bin/chown -hR mediagoblin:mediagoblin /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=main
+ 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-paster.service
+ sudo systemctl start mediagoblin-celeryd.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
/srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
/srv/mediagoblin.example.org/mediagoblin/paste.ini \
--pid-file=/var/run/mediagoblin.pid \
- --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
+ --server-name=main
The above configuration places MediaGoblin in "always eager" mode
with Celery, this means that submissions of content will be processed
/srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
/srv/mediagoblin.example.org/mediagoblin/paste.ini \
--pid-file=/var/run/mediagoblin.pid \
- --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
+ --server-name=main
+
-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
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
.. _`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
projects / mediagoblin.git / blobdiff