docs/source/siteadmin/production-deployments.rst

   1 .. MediaGoblin Documentation
   2
   3    Written in 2011, 2012, 2013, 2014, 2015 by MediaGoblin contributors
   4
   5    To the extent possible under law, the author(s) have dedicated all
   6    copyright and related and neighboring rights to this software to
   7    the public domain worldwide. This software is distributed without
   8    any warranty.
   9
  10    You should have received a copy of the CC0 Public Domain
  11    Dedication along with this software. If not, see
  12    <http://creativecommons.org/publicdomain/zero/1.0/>.
  13
  14 =========================================
  15 Considerations for Production Deployments
  16 =========================================
  17
  18 This document contains a number of suggestions for deploying
  19 MediaGoblin in actual production environments. Consider
  20 ":doc:`deploying`" for a basic overview of how to deploy MediaGoblin.
  21
  22 Deploy with paste
  23 -----------------
  24
  25 The MediaGoblin WSGI application instance you get with ``./lazyserver.sh`` is
  26 not ideal for a production MediaGoblin deployment. Ideally, you should be able
  27 to use a systemd service file or an init script to launch and restart the
  28 MediaGoblin process.
  29
  30 We will explore setting up MediaGoblin systemd service files and init scripts,
  31 but first we need to create the directory that will store the MediaGoblin logs.
  32
  33
  34 .. _create-log-file-dir:
  35
  36 Create the directory for your log file:
  37 ---------------------------------------
  38
  39 Production logs for the MediaGoblin application are kept in the
  40 ``/var/log/mediagoblin`` directory.  Create the directory and give it the
  41 proper permissions::
  42
  43     sudo mkdir -p /var/log/mediagoblin && sudo chown -hR mediagoblin:mediagoblin /var/log/mediagoblin
  44
  45
  46 .. _systemd-service-files:
  47
  48 Use systemd service files
  49 -------------------------
  50
  51 If your operating system uses systemd, you can use systemd ``service files``
  52 to manage both the Celery and Paste processes. Place the following service
  53 files in the ``/etc/systemd/system/`` directory.
  54
  55 The first file should be named ``mediagoblin-celeryd.service``. Be sure to
  56 modify it to suit your environment's setup:
  57
  58 .. code-block:: bash
  59
  60     # Set the WorkingDirectory, Environment and ExecStart values to match your environment.
  61     # If using Debian/Ubuntu, mkdir and chown are located in /bin/mkdir and /bin/chown, respectively.
  62     # If using Fedora/CentOS/Red Hat, mkdir and chown are located in /usr/bin/mkdir and /usr/bin/chown, respectively.
  63
  64     [Unit]
  65     Description=Mediagoblin Celeryd
  66
  67     [Service]
  68     User=mediagoblin
  69     Group=mediagoblin
  70     Type=simple
  71     WorkingDirectory=/srv/mediagoblin.example.org/mediagoblin
  72     # Create directory for PID (if needed) and set ownership
  73     ExecStartPre=/bin/mkdir -p /run/mediagoblin
  74     ExecStartPre=/bin/chown -hR mediagoblin:mediagoblin /run/mediagoblin
  75     # Celery process will run as the `mediagoblin` user after start.
  76     Environment=MEDIAGOBLIN_CONFIG=/srv/mediagoblin.example.org/mediagoblin/mediagoblin_local.ini \
  77                 CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery
  78     ExecStart=/srv/mediagoblin.example.org/mediagoblin/bin/celery worker \
  79                   --logfile=/var/log/mediagoblin/celery.log \
  80                   --loglevel=INFO
  81     PIDFile=/run/mediagoblin/mediagoblin-celeryd.pid
  82
  83     [Install]
  84     WantedBy=multi-user.target
  85
  86
  87 The second file should be named ``mediagoblin-paster.service``:
  88
  89
  90 .. code-block:: bash
  91
  92     # Set the WorkingDirectory, Environment and ExecStart values to match your environment.
  93     # If using Debian/Ubuntu, mkdir and chown are located in /bin/mkdir and /bin/chown, respectively.
  94     # If using Fedora/CentOS/Red Hat, mkdir and chown are located in /usr/bin/mkdir and /usr/bin/chown, respectively.
  95     [Unit]
  96     Description=Mediagoblin
  97
  98     [Service]
  99     Type=forking
 100     User=mediagoblin
 101     Group=mediagoblin
 102     Environment=CELERY_ALWAYS_EAGER=false
 103     WorkingDirectory=/srv/mediagoblin.example.org/mediagoblin
 104     # Start mg-paster process as root, then switch to mediagoblin user/group
 105     PermissionsStartOnly=true
 106     ExecStartPre=-/bin/mkdir -p /run/mediagoblin
 107     ExecStartPre=/bin/chown -hR mediagoblin:mediagoblin /run/mediagoblin
 108
 109     ExecStart=/srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
 110                   /srv/mediagoblin.example.org/mediagoblin/paste_local.ini \
 111                   --pid-file=/var/run/mediagoblin/mediagoblin.pid \
 112                   --log-file=/var/log/mediagoblin/mediagoblin.log \
 113                   --daemon \
 114                   --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
 115     ExecStop=/srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
 116                  --pid-file=/var/run/mediagoblin/mediagoblin.pid \
 117                  /srv/mediagoblin.example.org/mediagoblin/paste_local.ini stop
 118     PIDFile=/var/run/mediagoblin/mediagoblin.pid
 119
 120     [Install]
 121     WantedBy=multi-user.target
 122
 123
 124
 125 Enable these processes to start at boot by entering::
 126
 127     sudo systemctl enable mediagoblin-celeryd.service && sudo systemctl enable mediagoblin-paster.service
 128
 129
 130 Start the processes for the current session with::
 131
 132     sudo systemctl start mediagoblin-celeryd.service && sudo systemctl start mediagoblin-paster.service
 133
 134
 135 If either command above gives you an error, you can investigate the cause of
 136 the error by entering::
 137
 138     sudo systemctl status mediagoblin-celeryd.service  or
 139     sudo systemctl status mediagoblin-paster.service
 140
 141 The above ``systemctl status`` command is also useful if you ever want to
 142 confirm that a process is still running. If you make any changes to the service
 143 files, you can reload the service files by entering::
 144
 145     sudo systemctl daemon-reload
 146
 147 After entering that command, you can attempt to start the Celery or Paste
 148 processes again.
 149
 150 .. _init-script:
 151
 152 Use an init script
 153 ------------------
 154
 155 If your system does not use systemd, you can use the following command as the
 156 basis for an init script:
 157
 158 .. code-block:: bash
 159
 160     CELERY_ALWAYS_EAGER=true \
 161      /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
 162      /srv/mediagoblin.example.org/mediagoblin/paste.ini \
 163      --pid-file=/var/run/mediagoblin.pid \
 164      --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
 165
 166 The above configuration places MediaGoblin in "always eager" mode
 167 with Celery, this means that submissions of content will be processed
 168 synchronously, and the user will advance to the next page only after
 169 processing is complete. If we take Celery out of "always eager mode,"
 170 the user will be able to immediately return to the MediaGoblin site
 171 while processing is ongoing. In these cases, use the following command
 172 as the basis for your script:
 173
 174 .. code-block:: bash
 175
 176     CELERY_ALWAYS_EAGER=false \
 177      /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
 178      /srv/mediagoblin.example.org/mediagoblin/paste.ini \
 179      --pid-file=/var/run/mediagoblin.pid \
 180      --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
 181
 182
 183 Members of the MediaGoblin community have provided init scripts for the
 184 following GNU/Linux distributions:
 185
 186 Debian
 187   * `GNU MediaGoblin init scripts
 188     <https://github.com/joar/mediagoblin-init-scripts>`_
 189     by `Joar Wandborg <http://wandborg.se>`_
 190
 191 Arch Linux
 192   * `MediaGoblin - ArchLinux rc.d scripts
 193     <http://whird.jpope.org/2012/04/14/mediagoblin-archlinux-rcd-scripts>`_
 194     by `Jeremy Pope <http://jpope.org/>`_
 195   * `Mediagoblin init script on Archlinux
 196     <http://chimo.chromic.org/2012/03/01/mediagoblin-init-script-on-archlinux/>`_
 197     by `Chimo <http://chimo.chromic.org/>`_
 198
 199 You can reference these scripts to create an init script for your own operating
 200 system. Similar scripts will be in your system's ``/etc/init.d/``
 201 or ``/etc/rc.d/`` directory, but the specifics of an init script will vary from
 202 one distribution to the next.
 203
 204
 205 Separate celery
 206 ---------------
 207
 208 MediaGoblin uses `Celery`_ to handle heavy and long-running tasks. Celery can
 209 be launched in two ways:
 210
 211 1.  Embedded in the MediaGoblin WSGI application [#f-mediagoblin-wsgi-app]_.
 212     This is the way ``./lazyserver.sh`` does it for you. It's simple as you
 213     only have to run one process. The only bad thing with this is that the
 214     heavy and long-running tasks will run *in* the webserver, keeping the user
 215     waiting each time some heavy lifting is needed as in for example processing
 216     a video. This could lead to problems as an aborted connection will halt any
 217     processing and since most front-end web servers *will* terminate your
 218     connection if it doesn't get any response from the MediaGoblin WSGI
 219     application in a while.
 220
 221 2.  As a separate process communicating with the MediaGoblin WSGI application
 222     via a `broker`_. This offloads the heavy lifting from the MediaGoblin WSGI
 223     application and users will be able to continue to browse the site while the
 224     media is being processed in the background.
 225
 226 .. _`broker`: http://docs.celeryproject.org/en/latest/getting-started/brokers/
 227 .. _`celery`: http://www.celeryproject.org/
 228
 229
 230 .. [#f-mediagoblin-wsgi-app] The MediaGoblin WSGI application is the part that
 231     of MediaGoblin that processes HTTP requests.
 232
 233 To launch Celery separately from the MediaGoblin WSGI application:
 234
 235 1.  Make sure that the ``CELERY_ALWAYS_EAGER`` environment variable is unset or
 236     set to ``false`` when launching the MediaGoblin WSGI application.
 237 2.  Start the ``celeryd`` main process with
 238
 239     .. code-block:: bash
 240
 241         CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd
 242
 243 If you use our example systemd ``service files``, Celery will be set to the
 244 "CELERY_ALWAYS_EAGER=false" value by default. This will provide your users
 245 with the best user experience, as all media processing will be done in the
 246 background.
 247
 248 .. _sentry:
 249
 250 Set up sentry to monitor exceptions
 251 -----------------------------------
 252
 253 We have a plugin for `raven`_ integration, see the ":doc:`/plugindocs/raven`"
 254 documentation.
 255
 256 .. _`raven`: http://raven.readthedocs.org
 257
 258
 259 .. TODO insert init script here
 260 .. TODO are additional concerns ?
 261    .. Other Concerns
 262    .. --------------