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 aren't
21 easy package-manager-friendly methods to install it. However, doing a basic
22 install isn't too complex in and of itself. Following this deployment guide
23 will take you step-by-step through setting up your own instance of MediaGoblin.
25 Of course, when it comes to setting up web applications like MediaGoblin,
26 there's an almost infinite way to deploy things, so for now, we'll keep it
27 simple with some assumptions. We recommend a setup that combines MediaGoblin +
28 virtualenv + fastcgi + nginx on a .deb- or .rpm-based GNU/Linux distro.
30 Other deployment options (e.g., deploying on FreeBSD, Arch Linux, using
31 Apache, etc.) are possible, though! If you'd prefer a different deployment
33 `Deployment wiki page <http://wiki.mediagoblin.org/Deployment>`_.
37 These tools are for site administrators wanting to deploy a fresh
38 install. If you want to join in as a contributor, see our
39 `Hacking HOWTO <http://wiki.mediagoblin.org/HackingHowto>`_ instead.
43 Throughout the documentation we use the ``sudo`` command to indicate that
44 an instruction requires elevated user privileges to run. You can issue
45 these commands as the ``root`` user if you prefer.
47 If you need help configuring ``sudo``, see the
48 `Debian wiki <https://wiki.debian.org/sudo/>`_ or the
49 `Fedora Project wiki <https://fedoraproject.org/wiki/Configuring_Sudo/>`_.
58 MediaGoblin has the following core dependencies:
61 - `python-lxml <http://lxml.de/>`_
62 - `git <http://git-scm.com/>`_
63 - `SQLite <http://www.sqlite.org/>`_/`PostgreSQL <http://www.postgresql.org/>`_
64 - `Python Imaging Library <http://www.pythonware.com/products/pil/>`_ (PIL)
65 - `virtualenv <http://www.virtualenv.org/>`_
66 - `nodejs <https://nodejs.org>`_
68 On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and
69 derivatives) issue the following command::
71 sudo apt-get install git-core python python-dev python-lxml \
72 python-imaging python-virtualenv npm nodejs-legacy automake \
75 On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the
78 sudo yum install python-paste-deploy python-paste-script \
79 git-core python python-devel python-lxml python-imaging \
80 python-virtualenv npm automake nginx
87 MediaGoblin currently supports PostgreSQL and SQLite. The default is a
88 local SQLite database. This will "just work" for small deployments.
90 For medium to large deployments we recommend PostgreSQL.
92 If you don't want/need postgres, skip this section.
94 These are the packages needed for Debian Jessie (stable)::
96 sudo apt-get install postgresql postgresql-client python-psycopg2
98 These are the packages needed for an RPM-based system::
100 sudo yum install postgresql postgresql-server python-psycopg2
102 An rpm-based system also requires that you initialize and start the
103 PostgresSQL database with a few commands. The following commands are
104 not needed on a Debian-based platform, however::
106 sudo /usr/bin/postgresql-setup initdb
107 sudo systemctl enable postgresql
108 sudo systemctl start postgresql
110 The installation process will create a new *system* user named ``postgres``,
111 which will have privilegies sufficient to manage the database. We will create a
112 new database user with restricted privilegies and a new database owned by our
113 restricted database user for our MediaGoblin instance.
115 In this example, the database user will be ``mediagoblin`` and the database
116 name will be ``mediagoblin`` too.
118 We'll add these entities by first switching to the *postgres* account::
122 This will change your prompt to a shell prompt, such as *-bash-4.2$*. Enter
123 the following *createuser* and *createdb* commands at that prompt. We'll
124 create the *mediagoblin* database user first::
126 # this command and the one that follows are run as the ``postgres`` user:
127 createuser -A -D mediagoblin
129 Then we'll create the database where all of our MediaGoblin data will be stored::
131 createdb -E UNICODE -O mediagoblin mediagoblin
133 where the first ``mediagoblin`` is the database owner and the second
134 ``mediagoblin`` is the database name.
136 Type ``exit`` to exit from the 'postgres' user account.::
140 .. caution:: Where is the password?
142 These steps enable you to authenticate to the database in a password-less
143 manner via local UNIX authentication provided you run the MediaGoblin
144 application as a user with the same name as the user you created in
147 More on this in :ref:`Drop Privileges for MediaGoblin <drop-privileges-for-mediagoblin>`.
150 .. _drop-privileges-for-mediagoblin:
152 Drop Privileges for MediaGoblin
153 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
155 MediaGoblin does not require special permissions or elevated
156 access to run. As such, the preferred way to run MediaGoblin is to
157 create a dedicated, unprivileged system user for the sole purpose of running
158 MediaGoblin. Running MediaGoblin processes under an unpriviledged system user
159 helps to keep it more secure.
161 The following command (entered as root or with sudo) will create a
162 system account with a username of ``mediagoblin``. You may choose a different
163 username if you wish.
165 If you are using a Debian-based system, enter this command::
167 sudo useradd -c "GNU MediaGoblin system account" -d /var/lib/mediagoblin -m -r -g www-data mediagoblin
169 If you are using an RPM-based system, enter this command::
171 sudo useradd -c "GNU MediaGoblin system account" -d /var/lib/mediagoblin -m -r -g nginx mediagoblin
173 This will create a ``mediagoblin`` user and assign it to a group that is
174 associated with the web server. This will ensure that the web server can
175 read the media files (images, videos, etc.) that users upload.
177 We will also create a ``mediagoblin`` group and associate the mediagoblin
178 user with that group, as well::
180 sudo groupadd mediagoblin && sudo usermod --append -G mediagoblin mediagoblin
182 No password will be assigned to this account, and you will not be able
183 to log in as this user. To switch to this account, enter::
185 sudo su mediagoblin -s /bin/bash
187 To return to your regular user account after using the system account, type
190 .. _create-mediagoblin-directory:
192 Create a MediaGoblin Directory
193 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
195 You should create a working directory for MediaGoblin. This document
196 assumes your local git repository will be located at
197 ``/srv/mediagoblin.example.org/mediagoblin/``.
198 Substitute your prefered local deployment path as needed.
200 Setting up the working directory requires that we first create the directory
201 with elevated priviledges, and then assign ownership of the directory
202 to the unpriviledged system account.
204 To do this, enter the following command, changing the defaults to suit your
205 particular requirements. On a Debian-based platform you will enter this::
207 sudo mkdir -p /srv/mediagoblin.example.org && sudo chown -hR mediagoblin:www-data /srv/mediagoblin.example.org
209 On an RPM-based distribution, enter this command::
211 sudo mkdir -p /srv/mediagoblin.example.org && sudo chown -hR mediagoblin:nginx /srv/mediagoblin.example.org
215 Unless otherwise noted, the remainder of this document assumes that all
216 operations are performed using this unpriviledged account.
219 Install MediaGoblin and Virtualenv
220 ----------------------------------
222 We will now switch to our 'mediagoblin' system account, and then set up
223 our MediaGoblin source code repository and its necessary services.
224 You should modify these commands to suit your own environment.
226 Change to the MediaGoblin directory that you just created::
228 sudo su mediagoblin -s /bin/bash # to change to the 'mediagoblin' account
229 $ cd /srv/mediagoblin.example.org
231 Clone the MediaGoblin repository and set up the git submodules::
233 $ git clone git://git.savannah.gnu.org/mediagoblin.git -b stable
235 $ git submodule init && git submodule update
239 The MediaGoblin repository used to be on gitorious.org, but since
240 gitorious.org shut down, we had to move. We are presently on
241 Savannah. You may need to update your git repository location::
243 $ git remote set-url origin git://git.savannah.gnu.org/mediagoblin.git
245 Set up the hacking environment::
247 $ ./bootstrap.sh && ./configure && make
249 Create and set the proper permissions on the ``user_dev`` directory.
250 This directory will be used to store uploaded media files::
252 $ mkdir user_dev && chmod 750 user_dev
254 Assuming you are going to deploy with FastCGI, you should also install
257 $ ./bin/easy_install flup
259 The above provides an in-package install of ``virtualenv``. While this
260 is counter to the conventional ``virtualenv`` configuration, it is
261 more reliable and considerably easier to configure and illustrate. If
262 you're familiar with Python packaging you may consider deploying with
263 your preferred method.
267 What if you don't want an in-package ``virtualenv``? Maybe you
268 have your own ``virtualenv``, or you are building a MediaGoblin
269 package for a distribution. There's no need necessarily for the
270 virtualenv produced by ``./configure && make`` by default other
271 than attempting to simplify work for developers and people
272 deploying by hiding all the virtualenv and bower complexity.
274 If you want to install all of MediaGoblin's libraries
275 independently, that's totally fine! You can pass the flag
276 ``--without-virtualenv`` which will skip this step.
277 But you will need to install all those libraries manually and make
278 sure they are on your ``PYTHONPATH`` yourself! (You can still use
279 ``python setup.py develop`` to install some of those libraries,
280 but note that no ``./bin/python`` will be set up for you via this
281 method, since no virtualenv is set up for you!)
283 This concludes the initial configuration of the MediaGoblin
284 environment. In the future, when you update your
285 codebase, you should also run::
287 $ git submodule update && ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate
291 Note: If you are running an active site, depending on your server
292 configuration, you may need to stop it first or the dbupdate command
293 may hang (and it's certainly a good idea to restart it after the
297 Deploy MediaGoblin Services
298 ---------------------------
300 Edit site configuration
301 ~~~~~~~~~~~~~~~~~~~~~~~
303 A few basic properties must be set before MediaGoblin will work. First
304 make a copy of ``mediagoblin.ini`` and ``paste.ini`` for editing so the original
305 config files aren't lost (you likely won't need to edit the paste configuration,
306 but we'll make a local copy of it just in case)::
308 $ cp -av mediagoblin.ini mediagoblin_local.ini && cp -av paste.ini paste_local.ini
310 Then edit mediagoblin_local.ini:
311 - Set ``email_sender_address`` to the address you wish to be used as
312 the sender for system-generated emails
313 - Edit ``direct_remote_path``, ``base_dir``, and ``base_url`` if
314 your mediagoblin directory is not the root directory of your
318 Configure MediaGoblin to use the PostgreSQL database
319 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
321 If you are using postgres, edit the ``[mediagoblin]`` section in your
322 ``mediagoblin_local.ini`` and put in::
324 sql_engine = postgresql:///mediagoblin
326 if you are running the MediaGoblin application as the same 'user' as the
330 Update database data structures
331 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
333 Before you start using the database, you need to run::
337 to populate the database with the MediaGoblin data structures.
343 At this point MediaGoblin should be properly installed. You can
344 test the deployment with the following command::
346 $ ./lazyserver.sh --server-name=broadcast
348 You should be able to connect to the machine on port 6543 in your
349 browser to confirm that the service is operable.
351 The next series of commands will need to be run as a priviledged user. Type
352 exit to return to the root/sudo account.::
356 .. _webserver-config:
362 This configuration example will use nginx, however, you may
363 use any webserver of your choice as long as it supports the FastCGI
364 protocol. If you do not already have a web server, consider nginx, as
365 the configuration files may be more clear than the
368 Create a configuration file at
369 ``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link
370 into a directory that will be included in your ``nginx`` configuration
371 (e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with
372 one of the following commands.
374 On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and
375 derivatives) issue the following commands::
377 sudo ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/
378 sudo systemctl enable nginx
380 On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the
383 sudo ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/
384 sudo systemctl enable nginx
386 You can modify these commands and locations depending on your preferences and
387 the existing configuration of your nginx instance. The contents of
388 this ``nginx.conf`` file should be modeled on the following::
391 #################################################
392 # Stock useful config options, but ignore them :)
393 #################################################
394 include /etc/nginx/mime.types;
397 default_type application/octet-stream;
402 gzip_min_length 1024;
404 gzip_types text/plain application/x-javascript text/javascript text/xml text/css;
406 #####################################
407 # Mounting MediaGoblin stuff
408 # This is the section you should read
409 #####################################
411 # Change this to update the upload size limit for your users
412 client_max_body_size 8m;
414 # prevent attacks (someone uploading a .txt file that the browser
415 # interprets as an HTML file, etc.)
416 add_header X-Content-Type-Options nosniff;
418 server_name mediagoblin.example.org www.mediagoblin.example.org;
419 access_log /var/log/nginx/mediagoblin.example.access.log;
420 error_log /var/log/nginx/mediagoblin.example.error.log;
422 # MediaGoblin's stock static files: CSS, JS, etc.
423 location /mgoblin_static/ {
424 alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/;
427 # Instance specific media:
428 location /mgoblin_media/ {
429 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/;
432 # Theme static files (usually symlinked in)
433 location /theme_static/ {
434 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/theme_static/;
437 # Plugin static files (usually symlinked in)
438 location /plugin_static/ {
439 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/;
442 # Mounting MediaGoblin itself via FastCGI.
444 fastcgi_pass 127.0.0.1:26543;
445 include /etc/nginx/fastcgi_params;
447 # our understanding vs nginx's handling of script_name vs
448 # path_info don't match :)
449 fastcgi_param PATH_INFO $fastcgi_script_name;
450 fastcgi_param SCRIPT_NAME "";
454 The first four ``location`` directives instruct Nginx to serve the
455 static and uploaded files directly rather than through the MediaGoblin
456 process. This approach is faster and requires less memory.
460 The user who owns the Nginx process, normally ``www-data`` or ``nginx``,
461 requires execute permission on the directories ``static``,
462 ``public``, ``theme_static`` and ``plugin_static`` plus all their
463 parent directories. This user also requires read permission on all
464 the files within these directories. This is normally the default.
466 Nginx is now configured to serve the MediaGoblin application. Perform a quick
467 test to ensure that this configuration works::
471 If you encounter any errors, review your nginx configuration files, and try to
472 resolve them. If you do not encounter any errors, you can start your nginx
473 server with one of the following commands (depending on your environment)::
475 sudo /etc/init.d/nginx restart
476 sudo /etc/rc.d/nginx restart
477 sudo systemctl restart nginx
479 Now start MediaGoblin. Use the following command sequence as an
482 cd /srv/mediagoblin.example.org/mediagoblin/
483 su mediagoblin -s /bin/bash
484 ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
486 Visit the site you've set up in your browser by visiting
487 <http://mediagoblin.example.org>. You should see MediaGoblin!
491 The configuration described above is sufficient for development and
492 smaller deployments. However, for larger production deployments
493 with larger processing requirements, see the
494 ":doc:`production-deployments`" documentation.
500 Instructions and scripts for running MediaGoblin on an Apache server
501 can be found on the `MediaGoblin wiki <http://wiki.mediagoblin.org/Deployment>`_.
504 Should I Keep Open Registration Enabled?
505 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
507 Unfortunately, in this current release of MediaGoblin we are suffering
508 from spammers registering to public instances en masse. As such, you
511 a) Disable registration on your instance and just make
512 accounts for people you know and trust (eg via the `gmg adduser`
513 command). You can disable registration in your mediagoblin.ini
517 allow_registration = false
519 b) Enable a captcha plugin. But unfortunately, though some captcha
520 plugins exist, for various reasons we do not have any general
521 recommendations we can make at this point.
523 We hope to have a better solution to this situation shortly. We
524 apologize for the inconvenience in the meanwhile.
527 Security Considerations
528 ~~~~~~~~~~~~~~~~~~~~~~~
532 The directory ``user_dev/crypto/`` contains some very
534 Especially the ``itsdangeroussecret.bin`` is very important
535 for session security. Make sure not to leak its contents anywhere.
536 If the contents gets leaked nevertheless, delete your file
537 and restart the server, so that it creates a new secret key.
538 All previous sessions will be invalidated.