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 mediagoblin
96 then answer NO to *all* the questions::
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
102 then create the database all our MediaGoblin data should be stored in::
104 sudo -u postgres createdb -E UNICODE -O mediagoblin mediagoblin
106 where the first ``mediagoblin`` is the database owner and the second
107 ``mediagoblin`` is the database name.
109 .. caution:: Where is the password?
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
116 More on this in :ref:`Drop Privileges for MediaGoblin <drop-privileges-for-mediagoblin>`.
119 .. _drop-privileges-for-mediagoblin:
121 Drop Privileges for MediaGoblin
122 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
124 MediaGoblin does not require special permissions or elevated
125 access to run. As such, the prefered way to run MediaGoblin is to
126 create a dedicated, unpriviledged system user for sole the purpose of running
127 MediaGoblin. Running MediaGoblin processes under an unpriviledged system user
128 helps to keep it more secure.
130 The following command (entered as root or with sudo) will create a
131 system account with a username of ``mediagoblin``. You may choose a different
132 username if you wish.::
134 adduser --system mediagoblin
136 No password will be assigned to this account, and you will not be able
137 to log in as this user. To switch to this account, enter either::
139 sudo su - mediagoblin (if you have sudo permissions)
143 su - mediagoblin (if you have to use root permissions)
145 You may get a warning similar to this when entering these commands::
147 warning: cannot change directory to /home/mediagoblin: No such file or directory
149 You can disregard this warning. To return to your regular user account after
150 using the system account, just enter ``exit``.
154 Unless otherwise noted, the remainder of this document assumes that all
155 operations are performed using this unpriviledged account.
157 .. _create-mediagoblin-directory:
159 Create a MediaGoblin Directory
160 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
162 You should create a working directory for MediaGoblin. This document
163 assumes your local git repository will be located at
164 ``/srv/mediagoblin.example.org/mediagoblin/``.
165 Substitute your prefered local deployment path as needed.
167 Setting up the working directory requires that we first create the directory
168 with elevated priviledges, and then assign ownership of the directory
169 to the unpriviledged system account.
171 To do this, enter either of the following commands, changing the defaults
172 to suit your particular requirements::
174 sudo mkdir -p /srv/mediagoblin.example.org && sudo chown -hR mediagoblin:mediagoblin /srv/mediagobin.example.org
176 or (as the root user)::
178 mkdir -p /srv/mediagoblin.example.org && chown -hR mediagoblin:mediagoblin /srv/mediagobin.example.org
181 Install MediaGoblin and Virtualenv
182 ----------------------------------
186 MediaGoblin is still developing rapidly. As a result
187 the following instructions recommend installing from the ``master``
188 branch of the git repository. Eventually production deployments will
189 want to transition to running from more consistent releases.
191 We will now clone the MediaGoblin source code repository and setup and
192 configure the necessary services. Modify these commands to
193 suit your own environment. As a reminder, you should enter these
194 commands using your unpriviledged system account.
196 Change to the MediaGoblin directory that you just created::
198 cd /srv/mediagoblin.example.org
200 Clone the MediaGoblin repository and set up the git submodules::
202 git clone git://gitorious.org/mediagoblin/mediagoblin.git
204 git submodule init && git submodule update
206 Set up the in-package virtualenv via make::
208 ./bootstrap.sh && ./configure && make
212 Prefer not to use make, or want to use the "old way" of installing
213 MediaGoblin (maybe you know how to use virtualenv and python
214 packaging)? You still can! All that the above make script is doing
215 is installing an in-package virtualenv and running
217 ./bin/python setup.py develop
221 (NOTE: Is this still relevant?)
223 If you have problems here, consider trying to install virtualenv
224 with the ``--distribute`` or ``--no-site-packages`` options. If
225 your system's default Python is in the 3.x series you may need to
226 run ``virtualenv`` with the ``--python=python2.7`` or
227 ``--python=python2.6`` options.
229 The above provides an in-package install of ``virtualenv``. While this
230 is counter to the conventional ``virtualenv`` configuration, it is
231 more reliable and considerably easier to configure and illustrate. If
232 you're familiar with Python packaging you may consider deploying with
233 your preferred method.
235 Assuming you are going to deploy with FastCGI, you should also install
238 ./bin/easy_install flup
240 (Sometimes this breaks because flup's site is flakey. If it does for
243 ./bin/easy_install https://pypi.python.org/pypi/flup/1.0.3.dev-20110405
245 This concludes the initial configuration of the development
246 environment. In the future, when you update your
247 codebase, you should also run::
249 ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate && git submodule fetch
251 Note: If you are running an active site, depending on your server
252 configuration, you may need to stop it first or the dbupdate command
253 may hang (and it's certainly a good idea to restart it after the
257 Deploy MediaGoblin Services
258 ---------------------------
260 Edit site configuration
261 ~~~~~~~~~~~~~~~~~~~~~~~
263 A few basic properties must be set before MediaGoblin will work. First
264 make a copy of ``mediagoblin.ini`` for editing so the original config
267 cp mediagoblin.ini mediagoblin_local.ini
270 - Set ``email_sender_address`` to the address you wish to be used as
271 the sender for system-generated emails
272 - Edit ``direct_remote_path``, ``base_dir``, and ``base_url`` if
273 your mediagoblin directory is not the root directory of your
277 Configure MediaGoblin to use the PostgreSQL database
278 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
280 If you are using postgres, edit the ``[mediagoblin]`` section in your
281 ``mediagoblin_local.ini`` and put in::
283 sql_engine = postgresql:///mediagoblin
285 if you are running the MediaGoblin application as the same 'user' as the
289 Update database data structures
290 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
292 Before you start using the database, you need to run::
296 to populate the database with the MediaGoblin data structures.
302 At this point MediaGoblin should be properly installed. You can
303 test the deployment with the following command::
305 ./lazyserver.sh --server-name=broadcast
307 You should be able to connect to the machine on port 6543 in your
308 browser to confirm that the service is operable.
310 .. _webserver-config:
316 This configuration example will use nginx, however, you may
317 use any webserver of your choice as long as it supports the FastCGI
318 protocol. If you do not already have a web server, consider nginx, as
319 the configuration files may be more clear than the
322 Create a configuration file at
323 ``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link
324 into a directory that will be included in your ``nginx`` configuration
325 (e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with
326 one of the following commands (as the root user)::
328 ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/
329 ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/
331 Modify these commands and locations depending on your preferences and
332 the existing configuration of your nginx instance. The contents of
333 this ``nginx.conf`` file should be modeled on the following::
336 #################################################
337 # Stock useful config options, but ignore them :)
338 #################################################
339 include /etc/nginx/mime.types;
342 default_type application/octet-stream;
347 gzip_min_length 1024;
349 gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css;
351 #####################################
352 # Mounting MediaGoblin stuff
353 # This is the section you should read
354 #####################################
356 # Change this to update the upload size limit for your users
357 client_max_body_size 8m;
359 # prevent attacks (someone uploading a .txt file that the browser
360 # interprets as an HTML file, etc.)
361 add_header X-Content-Type-Options nosniff;
363 server_name mediagoblin.example.org www.mediagoblin.example.org;
364 access_log /var/log/nginx/mediagoblin.example.access.log;
365 error_log /var/log/nginx/mediagoblin.example.error.log;
367 # MediaGoblin's stock static files: CSS, JS, etc.
368 location /mgoblin_static/ {
369 alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/;
372 # Instance specific media:
373 location /mgoblin_media/ {
374 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/;
377 # Theme static files (usually symlinked in)
378 location /theme_static/ {
379 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/theme_static/;
382 # Plugin static files (usually symlinked in)
383 location /plugin_static/ {
384 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/;
387 # Mounting MediaGoblin itself via FastCGI.
389 fastcgi_pass 127.0.0.1:26543;
390 include /etc/nginx/fastcgi_params;
392 # our understanding vs nginx's handling of script_name vs
393 # path_info don't match :)
394 fastcgi_param PATH_INFO $fastcgi_script_name;
395 fastcgi_param SCRIPT_NAME "";
399 Now, nginx instance is configured to serve the MediaGoblin
400 application. Perform a quick test to ensure that this configuration
401 works. Restart nginx so it picks up your changes, with a command that
402 resembles one of the following (as the root user)::
404 sudo /etc/init.d/nginx restart
405 sudo /etc/rc.d/nginx restart
407 Now start MediaGoblin. Use the following command sequence as an
410 cd /srv/mediagoblin.example.org/mediagoblin/
411 ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
413 Visit the site you've set up in your browser by visiting
414 <http://mediagoblin.example.org>. You should see MediaGoblin!
418 The configuration described above is sufficient for development and
419 smaller deployments. However, for larger production deployments
420 with larger processing requirements, see the
421 ":doc:`production-deployments`" documentation.
427 Instructions and scripts for running MediaGoblin on an Apache server
428 can be found on the `MediaGoblin wiki <http://wiki.mediagoblin.org/Deployment>`_.
431 Security Considerations
432 ~~~~~~~~~~~~~~~~~~~~~~~
436 The directory ``user_dev/crypto/`` contains some very
438 Especially the ``itsdangeroussecret.bin`` is very important
439 for session security. Make sure not to leak its contents anywhere.
440 If the contents gets leaked nevertheless, delete your file
441 and restart the server, so that it creates a new secret key.
442 All previous sessions will be invalidated.