1 .. MediaGoblin Documentation
3 Written in 2011, 2012, 2013 by MediaGoblin contributors
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
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/>.
14 .. _deploying-chapter:
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.
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
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.
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>`_.
46 MediaGoblin has the following core dependencies:
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/>`_
55 On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and
56 derivatives) issue the following command::
58 sudo apt-get install git-core python python-dev python-lxml \
59 python-imaging python-virtualenv
61 On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the
64 yum install python-paste-deploy python-paste-script \
65 git-core python python-devel python-lxml python-imaging \
73 MediaGoblin currently supports PostgreSQL and SQLite. The default is a
74 local SQLite database. This will "just work" for small deployments.
76 For medium to large deployments we recommend PostgreSQL.
78 If you don't want/need postgres, skip this section.
80 These are the packages needed for Debian Wheezy (stable)::
82 sudo apt-get install postgresql postgresql-client python-psycopg2
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.
89 In this example, the database user will be ``mediagoblin`` and the database
90 name will be ``mediagoblin`` too.
92 To create our new user, run::
94 sudo -u postgres createuser -A -D mediagoblin
96 then create the database all our MediaGoblin data should be stored in::
98 sudo -u postgres createdb -E UNICODE -O mediagoblin mediagoblin
100 where the first ``mediagoblin`` is the database owner and the second
101 ``mediagoblin`` is the database name.
103 .. caution:: Where is the password?
105 These steps enable you to authenticate to the database in a password-less
106 manner via local UNIX authentication provided you run the MediaGoblin
107 application as a user with the same name as the user you created in
110 More on this in :ref:`Drop Privileges for MediaGoblin <drop-privileges-for-mediagoblin>`.
113 .. _drop-privileges-for-mediagoblin:
115 Drop Privileges for MediaGoblin
116 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
118 MediaGoblin does not require special permissions or elevated
119 access to run. As such, the preferred way to run MediaGoblin is to
120 create a dedicated, unprivileged system user for the sole purpose of running
121 MediaGoblin. Running MediaGoblin processes under an unpriviledged system user
122 helps to keep it more secure.
124 The following command (entered as root or with sudo) will create a
125 system account with a username of ``mediagoblin``. You may choose a different
126 username if you wish.::
128 adduser --system mediagoblin
130 No password will be assigned to this account, and you will not be able
131 to log in as this user. To switch to this account, enter either::
133 sudo -u mediagoblin /bin/bash # (if you have sudo permissions)
137 su mediagoblin -s /bin/bash # (if you have to use root permissions)
139 You may get a warning similar to this when entering these commands::
141 warning: cannot change directory to /home/mediagoblin: No such file or directory
143 You can disregard this warning. To return to your regular user account after
144 using the system account, just enter ``exit``.
148 Unless otherwise noted, the remainder of this document assumes that all
149 operations are performed using this unpriviledged account.
151 .. _create-mediagoblin-directory:
153 Create a MediaGoblin Directory
154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
156 You should create a working directory for MediaGoblin. This document
157 assumes your local git repository will be located at
158 ``/srv/mediagoblin.example.org/mediagoblin/``.
159 Substitute your prefered local deployment path as needed.
161 Setting up the working directory requires that we first create the directory
162 with elevated priviledges, and then assign ownership of the directory
163 to the unpriviledged system account.
165 To do this, enter either of the following commands, changing the defaults
166 to suit your particular requirements::
168 sudo mkdir -p /srv/mediagoblin.example.org && sudo chown -hR mediagoblin: /srv/mediagoblin.example.org
170 or (as the root user)::
172 mkdir -p /srv/mediagoblin.example.org && chown -hR mediagoblin: /srv/mediagoblin.example.org
175 Install MediaGoblin and Virtualenv
176 ----------------------------------
180 MediaGoblin is still developing rapidly. As a result
181 the following instructions recommend installing from the ``master``
182 branch of the git repository. Eventually production deployments will
183 want to transition to running from more consistent releases.
185 We will now clone the MediaGoblin source code repository and setup and
186 configure the necessary services. Modify these commands to
187 suit your own environment. As a reminder, you should enter these
188 commands using your unpriviledged system account.
190 Change to the MediaGoblin directory that you just created::
192 cd /srv/mediagoblin.example.org
194 Clone the MediaGoblin repository and set up the git submodules::
196 git clone git://gitorious.org/mediagoblin/mediagoblin.git -b stable
198 git submodule init && git submodule update
201 And set up the in-package virtualenv::
203 (virtualenv --python=python2 --system-site-packages . || virtualenv --python=python2 .) && ./bin/python setup.py develop
207 We presently have an **experimental** make-style deployment system. if
208 you'd like to try it, instead of the above command, you can run::
210 ./bootstrap.sh && ./configure && make
212 This also includes a number of nice features, such as keeping your
213 viratualenv up to date by simply running `make update`.
215 Note: this is liable to break. Use this method with caution.
217 You then need to make a local copy of mediagoblin.ini, if you don't have one::
219 cp --no-clobber mediagoblin.example.ini mediagoblin.ini
221 The above provides an in-package install of ``virtualenv``. While this
222 is counter to the conventional ``virtualenv`` configuration, it is
223 more reliable and considerably easier to configure and illustrate. If
224 you're familiar with Python packaging you may consider deploying with
225 your preferred method.
227 Assuming you are going to deploy with FastCGI, you should also install
230 ./bin/easy_install flup
232 (Sometimes this breaks because flup's site is flakey. If it does for
235 ./bin/easy_install https://pypi.python.org/pypi/flup/1.0.3.dev-20110405
237 This concludes the initial configuration of the development
238 environment. In the future, when you update your
239 codebase, you should also run::
241 git submodule update && ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate
243 Note: If you are running an active site, depending on your server
244 configuration, you may need to stop it first or the dbupdate command
245 may hang (and it's certainly a good idea to restart it after the
249 Deploy MediaGoblin Services
250 ---------------------------
252 Edit site configuration
253 ~~~~~~~~~~~~~~~~~~~~~~~
255 A few basic properties must be set before MediaGoblin will work. First
256 make a copy of ``mediagoblin.ini`` for editing so the original config
259 cp mediagoblin.ini mediagoblin_local.ini
262 - Set ``email_sender_address`` to the address you wish to be used as
263 the sender for system-generated emails
264 - Edit ``direct_remote_path``, ``base_dir``, and ``base_url`` if
265 your mediagoblin directory is not the root directory of your
269 Configure MediaGoblin to use the PostgreSQL database
270 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
272 If you are using postgres, edit the ``[mediagoblin]`` section in your
273 ``mediagoblin_local.ini`` and put in::
275 sql_engine = postgresql:///mediagoblin
277 if you are running the MediaGoblin application as the same 'user' as the
281 Update database data structures
282 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
284 Before you start using the database, you need to run::
288 to populate the database with the MediaGoblin data structures.
294 At this point MediaGoblin should be properly installed. You can
295 test the deployment with the following command::
297 ./lazyserver.sh --server-name=broadcast
299 You should be able to connect to the machine on port 6543 in your
300 browser to confirm that the service is operable.
302 .. _webserver-config:
308 This configuration example will use nginx, however, you may
309 use any webserver of your choice as long as it supports the FastCGI
310 protocol. If you do not already have a web server, consider nginx, as
311 the configuration files may be more clear than the
314 Create a configuration file at
315 ``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link
316 into a directory that will be included in your ``nginx`` configuration
317 (e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with
318 one of the following commands (as the root user)::
320 ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/
321 ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/
323 Modify these commands and locations depending on your preferences and
324 the existing configuration of your nginx instance. The contents of
325 this ``nginx.conf`` file should be modeled on the following::
328 #################################################
329 # Stock useful config options, but ignore them :)
330 #################################################
331 include /etc/nginx/mime.types;
334 default_type application/octet-stream;
339 gzip_min_length 1024;
341 gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css;
343 #####################################
344 # Mounting MediaGoblin stuff
345 # This is the section you should read
346 #####################################
348 # Change this to update the upload size limit for your users
349 client_max_body_size 8m;
351 # prevent attacks (someone uploading a .txt file that the browser
352 # interprets as an HTML file, etc.)
353 add_header X-Content-Type-Options nosniff;
355 server_name mediagoblin.example.org www.mediagoblin.example.org;
356 access_log /var/log/nginx/mediagoblin.example.access.log;
357 error_log /var/log/nginx/mediagoblin.example.error.log;
359 # MediaGoblin's stock static files: CSS, JS, etc.
360 location /mgoblin_static/ {
361 alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/;
364 # Instance specific media:
365 location /mgoblin_media/ {
366 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/;
369 # Theme static files (usually symlinked in)
370 location /theme_static/ {
371 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/theme_static/;
374 # Plugin static files (usually symlinked in)
375 location /plugin_static/ {
376 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/;
379 # Mounting MediaGoblin itself via FastCGI.
381 fastcgi_pass 127.0.0.1:26543;
382 include /etc/nginx/fastcgi_params;
384 # our understanding vs nginx's handling of script_name vs
385 # path_info don't match :)
386 fastcgi_param PATH_INFO $fastcgi_script_name;
387 fastcgi_param SCRIPT_NAME "";
391 The first four ``location`` directives instruct Nginx to serve the
392 static and uploaded files directly rather than through the MediaGoblin
393 process. This approach is faster and requires less memory.
397 The user who owns the Nginx process, normally ``www-data``,
398 requires execute permission on the directories ``static``,
399 ``public``, ``theme_static`` and ``plugin_static`` plus all their
400 parent directories. This user also requires read permission on all
401 the files within these directories. This is normally the default.
403 Now, nginx instance is configured to serve the MediaGoblin
404 application. Perform a quick test to ensure that this configuration
405 works. Restart nginx so it picks up your changes, with a command that
406 resembles one of the following (as the root user)::
408 sudo /etc/init.d/nginx restart
409 sudo /etc/rc.d/nginx restart
411 Now start MediaGoblin. Use the following command sequence as an
414 cd /srv/mediagoblin.example.org/mediagoblin/
415 ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
417 Visit the site you've set up in your browser by visiting
418 <http://mediagoblin.example.org>. You should see MediaGoblin!
422 The configuration described above is sufficient for development and
423 smaller deployments. However, for larger production deployments
424 with larger processing requirements, see the
425 ":doc:`production-deployments`" documentation.
431 Instructions and scripts for running MediaGoblin on an Apache server
432 can be found on the `MediaGoblin wiki <http://wiki.mediagoblin.org/Deployment>`_.
435 Security Considerations
436 ~~~~~~~~~~~~~~~~~~~~~~~
440 The directory ``user_dev/crypto/`` contains some very
442 Especially the ``itsdangeroussecret.bin`` is very important
443 for session security. Make sure not to leak its contents anywhere.
444 If the contents gets leaked nevertheless, delete your file
445 and restart the server, so that it creates a new secret key.
446 All previous sessions will be invalidated.