1 .. MediaGoblin Documentation
3 Written in 2011, 2012 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 (testing)::
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 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.
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.
136 This document assumes that all operations are performed as this
137 user. To drop privileges to this user, run the following command::
141 Where, "``[mediagoblin]``" is the username of the system user that will
144 Install MediaGoblin and Virtualenv
145 ----------------------------------
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.
154 Issue the following commands, to create and change the working
155 directory. Modify these commands to reflect your own environment::
157 mkdir -p /srv/mediagoblin.example.org/
158 cd /srv/mediagoblin.example.org/
160 Clone the MediaGoblin repository and set up the git submodules::
162 git clone git://gitorious.org/mediagoblin/mediagoblin.git
163 git submodule init && git submodule update
165 And set up the in-package virtualenv::
168 (virtualenv --system-site-packages . || virtualenv .) && ./bin/python setup.py develop
172 If you have problems here, consider trying to install virtualenv
173 with the ``--distribute`` or ``--no-site-packages`` options. If
174 your system's default Python is in the 3.x series you may need to
175 run ``virtualenv`` with the ``--python=python2.7`` or
176 ``--python=python2.6`` options.
178 The above provides an in-package install of ``virtualenv``. While this
179 is counter to the conventional ``virtualenv`` configuration, it is
180 more reliable and considerably easier to configure and illustrate. If
181 you're familiar with Python packaging you may consider deploying with
182 your preferred method.
184 Assuming you are going to deploy with FastCGI, you should also install
187 ./bin/easy_install flup
189 (Sometimes this breaks because flup's site is flakey. If it does for
192 ./bin/easy_install https://pypi.python.org/pypi/flup/1.0.3.dev-20110405
194 This concludes the initial configuration of the development
195 environment. In the future, when you update your
196 codebase, you should also run::
198 ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate && git submodule fetch
200 Note: If you are running an active site, depending on your server
201 configuration, you may need to stop it first or the dbupdate command
202 may hang (and it's certainly a good idea to restart it after the
206 Deploy MediaGoblin Services
207 ---------------------------
209 Edit site configuration
210 ~~~~~~~~~~~~~~~~~~~~~~~
212 A few basic properties must be set before MediaGoblin will work. First
213 make a copy of ``mediagoblin.ini`` for editing so the original config
216 cp mediagoblin.ini mediagoblin_local.ini
219 - Set ``email_sender_address`` to the address you wish to be used as
220 the sender for system-generated emails
221 - Edit ``direct_remote_path``, ``base_dir``, and ``base_url`` if
222 your mediagoblin directory is not the root directory of your
226 Configure MediaGoblin to use the PostgreSQL database
227 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
229 If you are using postgres, edit the ``[mediagoblin]`` section in your
230 ``mediagoblin_local.ini`` and put in::
232 sql_engine = postgresql:///mediagoblin
234 if you are running the MediaGoblin application as the same 'user' as the
238 Update database data structures
239 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
241 Before you start using the database, you need to run::
245 to populate the database with the MediaGoblin data structures.
251 At this point MediaGoblin should be properly installed. You can
252 test the deployment with the following command::
254 ./lazyserver.sh --server-name=broadcast
256 You should be able to connect to the machine on port 6543 in your
257 browser to confirm that the service is operable.
259 .. _webserver-config:
265 This configuration example will use nginx, however, you may
266 use any webserver of your choice as long as it supports the FastCGI
267 protocol. If you do not already have a web server, consider nginx, as
268 the configuration files may be more clear than the
271 Create a configuration file at
272 ``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link
273 into a directory that will be included in your ``nginx`` configuration
274 (e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with
275 one of the following commands (as the root user)::
277 ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/
278 ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/
280 Modify these commands and locations depending on your preferences and
281 the existing configuration of your nginx instance. The contents of
282 this ``nginx.conf`` file should be modeled on the following::
285 #################################################
286 # Stock useful config options, but ignore them :)
287 #################################################
288 include /etc/nginx/mime.types;
291 default_type application/octet-stream;
296 gzip_min_length 1024;
298 gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css;
300 #####################################
301 # Mounting MediaGoblin stuff
302 # This is the section you should read
303 #####################################
305 # Change this to update the upload size limit for your users
306 client_max_body_size 8m;
308 # prevent attacks (someone uploading a .txt file that the browser
309 # interprets as an HTML file, etc.)
310 add_header X-Content-Type-Options nosniff;
312 server_name mediagoblin.example.org www.mediagoblin.example.org;
313 access_log /var/log/nginx/mediagoblin.example.access.log;
314 error_log /var/log/nginx/mediagoblin.example.error.log;
316 # MediaGoblin's stock static files: CSS, JS, etc.
317 location /mgoblin_static/ {
318 alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/;
321 # Instance specific media:
322 location /mgoblin_media/ {
323 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/;
326 # Theme static files (usually symlinked in)
327 location /theme_static/ {
328 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/theme_static/;
331 # Plugin static files (usually symlinked in)
332 location /plugin_static/ {
333 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/;
336 # Mounting MediaGoblin itself via FastCGI.
338 fastcgi_pass 127.0.0.1:26543;
339 include /etc/nginx/fastcgi_params;
341 # our understanding vs nginx's handling of script_name vs
342 # path_info don't match :)
343 fastcgi_param PATH_INFO $fastcgi_script_name;
344 fastcgi_param SCRIPT_NAME "";
348 Now, nginx instance is configured to serve the MediaGoblin
349 application. Perform a quick test to ensure that this configuration
350 works. Restart nginx so it picks up your changes, with a command that
351 resembles one of the following (as the root user)::
353 sudo /etc/init.d/nginx restart
354 sudo /etc/rc.d/nginx restart
356 Now start MediaGoblin. Use the following command sequence as an
359 cd /srv/mediagoblin.example.org/mediagoblin/
360 ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
362 Visit the site you've set up in your browser by visiting
363 <http://mediagoblin.example.org>. You should see MediaGoblin!
367 The configuration described above is sufficient for development and
368 smaller deployments. However, for larger production deployments
369 with larger processing requirements, see the
370 ":doc:`production-deployments`" documentation.
376 Instructions and scripts for running MediaGoblin on an Apache server
377 can be found on the `MediaGoblin wiki <http://wiki.mediagoblin.org/Deployment>`_.
380 Security Considerations
381 ~~~~~~~~~~~~~~~~~~~~~~~
385 The directory ``user_dev/crypto/`` contains some very
387 Especially the ``itsdangeroussecret.bin`` is very important
388 for session security. Make sure not to leak its contents anywhere.
389 If the contents gets leaked nevertheless, delete your file
390 and restart the server, so that it creates a new secret key.
391 All previous sessions will be invalifated then.