diff options
Diffstat (limited to 'docs/source')
| -rw-r--r-- | docs/source/siteadmin/production-deployments.rst | 187 |
1 files changed, 157 insertions, 30 deletions
diff --git a/docs/source/siteadmin/production-deployments.rst b/docs/source/siteadmin/production-deployments.rst index 839d3ce5..0443f079 100644 --- a/docs/source/siteadmin/production-deployments.rst +++ b/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 -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 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 |