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-paster.service
 133     sudo systemctl start mediagoblin-celeryd.service
 134
 135
 136 If either command above gives you an error, you can investigate the cause of
 137 the error by entering::
 138
 139     sudo systemctl status mediagoblin-celeryd.service  or
 140     sudo systemctl status mediagoblin-paster.service
 141
 142 The above ``systemctl status`` command is also useful if you ever want to
 143 confirm that a process is still running. If you make any changes to the service
 144 files, you can reload the service files by entering::
 145
 146     sudo systemctl daemon-reload
 147
 148 After entering that command, you can attempt to start the Celery or Paste
 149 processes again.
 150
 151 .. _init-script:
 152
 153 Use an init script
 154 ------------------
 155
 156 If your system does not use systemd, you can use the following command as the
 157 basis for an init script:
 158
 159 .. code-block:: bash
 160
 161     CELERY_ALWAYS_EAGER=true \
 162      /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
 163      /srv/mediagoblin.example.org/mediagoblin/paste.ini \
 164      --pid-file=/var/run/mediagoblin.pid \
 165      --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
 166
 167 The above configuration places MediaGoblin in "always eager" mode
 168 with Celery, this means that submissions of content will be processed
 169 synchronously, and the user will advance to the next page only after
 170 processing is complete. If we take Celery out of "always eager mode,"
 171 the user will be able to immediately return to the MediaGoblin site
 172 while processing is ongoing. In these cases, use the following command
 173 as the basis for your script:
 174
 175 .. code-block:: bash
 176
 177     CELERY_ALWAYS_EAGER=false \
 178      /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
 179      /srv/mediagoblin.example.org/mediagoblin/paste.ini \
 180      --pid-file=/var/run/mediagoblin.pid \
 181      --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
 182
 183
 184 Members of the MediaGoblin community have provided init scripts for the
 185 following GNU/Linux distributions:
 186
 187 Debian
 188   * `GNU MediaGoblin init scripts
 189     <https://github.com/joar/mediagoblin-init-scripts>`_
 190     by `Joar Wandborg <http://wandborg.se>`_
 191
 192 Arch Linux
 193   * `MediaGoblin - ArchLinux rc.d scripts
 194     <http://whird.jpope.org/2012/04/14/mediagoblin-archlinux-rcd-scripts>`_
 195     by `Jeremy Pope <http://jpope.org/>`_
 196   * `Mediagoblin init script on Archlinux
 197     <http://chimo.chromic.org/2012/03/01/mediagoblin-init-script-on-archlinux/>`_
 198     by `Chimo <http://chimo.chromic.org/>`_
 199
 200 You can reference these scripts to create an init script for your own operating
 201 system. Similar scripts will be in your system's ``/etc/init.d/``
 202 or ``/etc/rc.d/`` directory, but the specifics of an init script will vary from
 203 one distribution to the next.
 204
 205
 206 Separate celery
 207 ---------------
 208
 209 MediaGoblin uses `Celery`_ to handle heavy and long-running tasks. Celery can
 210 be launched in two ways:
 211
 212 1.  Embedded in the MediaGoblin WSGI application [#f-mediagoblin-wsgi-app]_.
 213     This is the way ``./lazyserver.sh`` does it for you. It's simple as you
 214     only have to run one process. The only bad thing with this is that the
 215     heavy and long-running tasks will run *in* the webserver, keeping the user
 216     waiting each time some heavy lifting is needed as in for example processing
 217     a video. This could lead to problems as an aborted connection will halt any
 218     processing and since most front-end web servers *will* terminate your
 219     connection if it doesn't get any response from the MediaGoblin WSGI
 220     application in a while.
 221
 222 2.  As a separate process communicating with the MediaGoblin WSGI application
 223     via a `broker`_. This offloads the heavy lifting from the MediaGoblin WSGI
 224     application and users will be able to continue to browse the site while the
 225     media is being processed in the background.
 226
 227 .. _`broker`: http://docs.celeryproject.org/en/latest/getting-started/brokers/
 228 .. _`celery`: http://www.celeryproject.org/
 229
 230
 231 .. [#f-mediagoblin-wsgi-app] The MediaGoblin WSGI application is the part that
 232     of MediaGoblin that processes HTTP requests.
 233
 234 To launch Celery separately from the MediaGoblin WSGI application:
 235
 236 1.  Make sure that the ``CELERY_ALWAYS_EAGER`` environment variable is unset or
 237     set to ``false`` when launching the MediaGoblin WSGI application.
 238 2.  Start the ``celeryd`` main process with
 239
 240     .. code-block:: bash
 241
 242         CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd
 243
 244 If you use our example systemd ``service files``, Celery will be set to the
 245 "CELERY_ALWAYS_EAGER=false" value by default. This will provide your users
 246 with the best user experience, as all media processing will be done in the
 247 background.
 248
 249 .. _sentry:
 250
 251 Set up sentry to monitor exceptions
 252 -----------------------------------
 253
 254 We have a plugin for `raven`_ integration, see the ":doc:`/plugindocs/raven`"
 255 documentation.
 256
 257 .. _`raven`: http://raven.readthedocs.org
 258
 259
 260 .. TODO insert init script here
 261 .. TODO are additional concerns ?
 262    .. Other Concerns
 263    .. --------------