docs/source/siteadmin/deploying.rst

   1 .. MediaGoblin Documentation
   2
   3    Written in 2011, 2012 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 .. _deploying-chapter:
  15
  16 =====================
  17 Deploying MediaGoblin
  18 =====================
  19
  20 GNU MediaGoblin is fairly new and so at the time of writing, there
  21 aren't easy package-manager-friendly methods to install MediaGoblin.
  22 However, doing a basic install isn't too complex in and of itself.
  23
  24 There's an almost infinite way to deploy things... for now, we'll keep
  25 it simple with some assumptions and use a setup that combines
  26 mediagoblin + virtualenv + fastcgi + nginx on a .deb or .rpm based
  27 GNU/Linux distro.
  28
  29 .. note::
  30
  31    These tools are for site administrators wanting to deploy a fresh
  32    install.  If instead you want to join in as a contributor, see our
  33    `Hacking HOWTO <http://wiki.mediagoblin.org/HackingHowto>`_ instead.
  34
  35    There are also many ways to install servers... for the sake of
  36    simplicity, our instructions below describe installing with nginx.
  37    For more recipes, including Apache, see
  38    `our wiki <http://wiki.mediagoblin.org/Deployment>`_.
  39
  40 Prepare System
  41 --------------
  42
  43 Dependencies
  44 ~~~~~~~~~~~~
  45
  46 MediaGoblin has the following core dependencies:
  47
  48 - Python 2.6 or 2.7
  49 - `python-lxml <http://lxml.de/>`_
  50 - `git <http://git-scm.com/>`_
  51 - `SQLite <http://www.sqlite.org/>`_/`PostgreSQL <http://www.postgresql.org/>`_
  52 - `Python Imaging Library <http://www.pythonware.com/products/pil/>`_  (PIL)
  53 - `virtualenv <http://www.virtualenv.org/>`_
  54
  55 On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and
  56 derivatives) issue the following command::
  57
  58     sudo apt-get install git-core python python-dev python-lxml \
  59         python-imaging python-virtualenv
  60
  61 On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the
  62 following command::
  63
  64     yum install python-paste-deploy python-paste-script \
  65         git-core python python-devel python-lxml python-imaging \
  66         python-virtualenv
  67
  68 Configure PostgreSQL
  69 ~~~~~~~~~~~~~~~~~~~~
  70
  71 .. note::
  72
  73    MediaGoblin currently supports PostgreSQL and SQLite. The default is a
  74    local SQLite database. This will "just work" for small deployments.
  75
  76    For medium to large deployments we recommend PostgreSQL.
  77
  78    If you don't want/need postgres, skip this section.
  79
  80 These are the packages needed for Debian Wheezy (testing)::
  81
  82     sudo apt-get install postgresql postgresql-client python-psycopg2
  83
  84 The installation process will create a new *system* user named ``postgres``,
  85 it will have privilegies sufficient to manage the database. We will create a
  86 new database user with restricted privilegies and a new database owned by our
  87 restricted database user for our MediaGoblin instance.
  88
  89 In this example, the database user will be ``mediagoblin`` and the database
  90 name will be ``mediagoblin`` too.
  91
  92 To create our new user, run::
  93
  94     sudo -u postgres createuser mediagoblin
  95
  96 then answer NO to *all* the questions::
  97
  98     Shall the new role be a superuser? (y/n) n
  99     Shall the new role be allowed to create databases? (y/n) n
 100     Shall the new role be allowed to create more new roles? (y/n) n
 101
 102 then create the database all our MediaGoblin data should be stored in::
 103
 104     sudo -u postgres createdb -E UNICODE -O mediagoblin mediagoblin
 105
 106 where the first ``mediagoblin`` is the database owner and the second
 107 ``mediagoblin`` is the database name.
 108
 109 .. caution:: Where is the password?
 110
 111     These steps enable you to authenticate to the database in a password-less
 112     manner via local UNIX authentication provided you run the MediaGoblin
 113     application as a user with the same name as the user you created in
 114     PostgreSQL.
 115
 116     More on this in :ref:`Drop Privileges for MediaGoblin <drop-privileges-for-mediagoblin>`.
 117
 118
 119 .. _drop-privileges-for-mediagoblin:
 120
 121 Drop Privileges for MediaGoblin
 122 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 123
 124 As MediaGoblin does not require special permissions or elevated
 125 access, you should run MediaGoblin under an existing non-root user or
 126 preferably create a dedicated user for the purpose of running
 127 MediaGoblin. Consult your distribution's documentation on how to
 128 create "system account" or dedicated service user. Ensure that it is
 129 not possible to log in to your system with as this user.
 130
 131 You should create a working directory for MediaGoblin. This document
 132 assumes your local git repository will be located at
 133 ``/srv/mediagoblin.example.org/mediagoblin/`` for this documentation.
 134 Substitute your prefer ed local deployment path as needed.
 135
 136 This document assumes that all operations are performed as this
 137 user. To drop privileges to this user, run the following command::
 138
 139       su - [mediagoblin]
 140
 141 Where, "``[mediagoblin]``" is the username of the system user that will
 142 run MediaGoblin.
 143
 144 Install MediaGoblin and Virtualenv
 145 ----------------------------------
 146
 147 .. note::
 148
 149    MediaGoblin is still developing rapidly. As a result
 150    the following instructions recommend installing from the ``master``
 151    branch of the git repository. Eventually production deployments will
 152    want to transition to running from more consistent releases.
 153
 154 Issue the following commands, to create and change the working
 155 directory. Modify these commands to reflect your own environment::
 156
 157     mkdir -p /srv/mediagoblin.example.org/
 158     cd /srv/mediagoblin.example.org/
 159
 160 Clone the MediaGoblin repository::
 161
 162     git clone git://gitorious.org/mediagoblin/mediagoblin.git
 163
 164 And set up the in-package virtualenv::
 165
 166     cd mediagoblin
 167     (virtualenv --system-site-packages . || virtualenv .) && ./bin/python setup.py develop
 168
 169 .. note::
 170
 171    If you have problems here, consider trying to install virtualenv
 172    with the ``--distribute`` or ``--no-site-packages`` options. If
 173    your system's default Python is in the 3.x series you may need to
 174    run ``virtualenv`` with the  ``--python=python2.7`` or
 175    ``--python=python2.6`` options.
 176
 177 The above provides an in-package install of ``virtualenv``. While this
 178 is counter to the conventional ``virtualenv`` configuration, it is
 179 more reliable and considerably easier to configure and illustrate. If
 180 you're familiar with Python packaging you may consider deploying with
 181 your preferred method.
 182
 183 Assuming you are going to deploy with FastCGI, you should also install
 184 flup::
 185
 186     ./bin/easy_install flup
 187
 188 (Sometimes this breaks because flup's site is flakey.  If it does for
 189 you, try)::
 190
 191     ./bin/easy_install https://pypi.python.org/pypi/flup/1.0.3.dev-20110405
 192
 193 This concludes the initial configuration of the development
 194 environment. In the future, when you update your
 195 codebase, you should also run::
 196
 197     ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate
 198
 199 Note: If you are running an active site, depending on your server
 200 configuration, you may need to stop it first or the dbupdate command
 201 may hang (and it's certainly a good idea to restart it after the
 202 update)
 203
 204
 205 Deploy MediaGoblin Services
 206 ---------------------------
 207
 208 Configure MediaGoblin to use the PostgreSQL database
 209 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 210
 211 If you are using postgres, edit the ``[mediagoblin]`` section in your
 212 ``mediagoblin_local.ini`` and put in::
 213
 214     sql_engine = postgresql:///mediagoblin
 215
 216 if you are running the MediaGoblin application as the same 'user' as the
 217 database owner.
 218
 219
 220 Update database data structures
 221 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 222
 223 Before you start using the database, you need to run::
 224
 225     ./bin/gmg dbupdate
 226
 227 to populate the database with the MediaGoblin data structures.
 228
 229
 230 Test the Server
 231 ~~~~~~~~~~~~~~~
 232
 233 At this point MediaGoblin should be properly installed.  You can
 234 test the deployment with the following command::
 235
 236     ./lazyserver.sh --server-name=broadcast
 237
 238 You should be able to connect to the machine on port 6543 in your
 239 browser to confirm that the service is operable.
 240
 241 .. _webserver-config:
 242
 243 Connect the Webserver to MediaGoblin with FastCGI
 244 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 245
 246 This section describes how to configure MediaGoblin to work via
 247 FastCGI. Our configuration example will use nginx, however, you may
 248 use any webserver of your choice as long as it supports the FastCGI
 249 protocol. If you do not already have a web server, consider nginx, as
 250 the configuration files may be more clear than the
 251 alternatives.
 252
 253 Create a configuration file at
 254 ``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link
 255 into a directory that will be included in your ``nginx`` configuration
 256 (e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with
 257 one of the following commands (as the root user)::
 258
 259     ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/
 260     ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/
 261
 262 Modify these commands and locations depending on your preferences and
 263 the existing configuration of your nginx instance. The contents of
 264 this ``nginx.conf`` file should be modeled on the following::
 265
 266     server {
 267      #################################################
 268      # Stock useful config options, but ignore them :)
 269      #################################################
 270      include /etc/nginx/mime.types;
 271
 272      autoindex off;
 273      default_type  application/octet-stream;
 274      sendfile on;
 275
 276      # Gzip
 277      gzip on;
 278      gzip_min_length 1024;
 279      gzip_buffers 4 32k;
 280      gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css;
 281
 282      #####################################
 283      # Mounting MediaGoblin stuff
 284      # This is the section you should read
 285      #####################################
 286
 287      # Change this to update the upload size limit for your users
 288      client_max_body_size 8m;
 289
 290      # prevent attacks (someone uploading a .txt file that the browser
 291      # interprets as an HTML file, etc.)
 292      add_header X-Content-Type-Options nosniff;
 293
 294      server_name mediagoblin.example.org www.mediagoblin.example.org;
 295      access_log /var/log/nginx/mediagoblin.example.access.log;
 296      error_log /var/log/nginx/mediagoblin.example.error.log;
 297
 298      # MediaGoblin's stock static files: CSS, JS, etc.
 299      location /mgoblin_static/ {
 300         alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/;
 301      }
 302
 303      # Instance specific media:
 304      location /mgoblin_media/ {
 305         alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/;
 306      }
 307
 308      # Theme static files (usually symlinked in)
 309      location /theme_static/ {
 310         alias /srv/mediagoblin.example.org/mediagoblin/user_dev/theme_static/;
 311      }
 312
 313      # Mounting MediaGoblin itself via FastCGI.
 314      location / {
 315         fastcgi_pass 127.0.0.1:26543;
 316         include /etc/nginx/fastcgi_params;
 317
 318         # our understanding vs nginx's handling of script_name vs
 319         # path_info don't match :)
 320         fastcgi_param PATH_INFO $fastcgi_script_name;
 321         fastcgi_param SCRIPT_NAME "";
 322      }
 323     }
 324
 325 Now, nginx instance is configured to serve the MediaGoblin
 326 application. Perform a quick test to ensure that this configuration
 327 works. Restart nginx so it picks up your changes, with a command that
 328 resembles one of the following (as the root user)::
 329
 330     sudo /etc/init.d/nginx restart
 331     sudo /etc/rc.d/nginx restart
 332
 333 Now start MediaGoblin. Use the following command sequence as an
 334 example::
 335
 336     cd /srv/mediagoblin.example.org/mediagoblin/
 337     ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
 338
 339 Visit the site you've set up in your browser by visiting
 340 <http://mediagoblin.example.org>. You should see MediaGoblin!
 341
 342 .. note::
 343
 344    The configuration described above is sufficient for development and
 345    smaller deployments. However, for larger production deployments
 346    with larger processing requirements, see the
 347    ":doc:`production-deployments`" documentation.