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 The above provides an in-package install of ``virtualenv``. While this
250 is counter to the conventional ``virtualenv`` configuration, it is
251 more reliable and considerably easier to configure and illustrate. If
252 you're familiar with Python packaging you may consider deploying with
253 your preferred method.
257 What if you don't want an in-package ``virtualenv``? Maybe you
258 have your own ``virtualenv``, or you are building a MediaGoblin
259 package for a distribution. There's no need necessarily for the
260 virtualenv produced by ``./configure && make`` by default other
261 than attempting to simplify work for developers and people
262 deploying by hiding all the virtualenv and bower complexity.
264 If you want to install all of MediaGoblin's libraries
265 independently, that's totally fine! You can pass the flag
266 ``--without-virtualenv`` which will skip this step.
267 But you will need to install all those libraries manually and make
268 sure they are on your ``PYTHONPATH`` yourself! (You can still use
269 ``python setup.py develop`` to install some of those libraries,
270 but note that no ``./bin/python`` will be set up for you via this
271 method, since no virtualenv is set up for you!)
273 Assuming you are going to deploy with FastCGI, you should also install
276 $ ./bin/easy_install flup
278 This concludes the initial configuration of the development
279 environment. In the future, when you update your
280 codebase, you should also run::
282 $ git submodule update && ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate
286 Note: If you are running an active site, depending on your server
287 configuration, you may need to stop it first or the dbupdate command
288 may hang (and it's certainly a good idea to restart it after the
292 Deploy MediaGoblin Services
293 ---------------------------
295 Edit site configuration
296 ~~~~~~~~~~~~~~~~~~~~~~~
298 A few basic properties must be set before MediaGoblin will work. First
299 make a copy of ``mediagoblin.ini`` and ``paste.ini`` for editing so the original
300 config files aren't lost (you likely won't need to edit the paste configuration,
301 but we'll make a local copy of it just in case)::
303 $ cp -av mediagoblin.ini mediagoblin_local.ini && cp -av paste.ini paste_local.ini
305 Then edit mediagoblin_local.ini:
306 - Set ``email_sender_address`` to the address you wish to be used as
307 the sender for system-generated emails
308 - Edit ``direct_remote_path``, ``base_dir``, and ``base_url`` if
309 your mediagoblin directory is not the root directory of your
313 Configure MediaGoblin to use the PostgreSQL database
314 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
316 If you are using postgres, edit the ``[mediagoblin]`` section in your
317 ``mediagoblin_local.ini`` and put in::
319 sql_engine = postgresql:///mediagoblin
321 if you are running the MediaGoblin application as the same 'user' as the
325 Update database data structures
326 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
328 Before you start using the database, you need to run::
332 to populate the database with the MediaGoblin data structures.
338 At this point MediaGoblin should be properly installed. You can
339 test the deployment with the following command::
341 $ ./lazyserver.sh --server-name=broadcast
343 You should be able to connect to the machine on port 6543 in your
344 browser to confirm that the service is operable.
346 The next series of commands will need to be run as a priviledged user. Type
347 exit to return to the root/sudo account.::
351 .. _webserver-config:
357 This configuration example will use nginx, however, you may
358 use any webserver of your choice as long as it supports the FastCGI
359 protocol. If you do not already have a web server, consider nginx, as
360 the configuration files may be more clear than the
363 Create a configuration file at
364 ``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link
365 into a directory that will be included in your ``nginx`` configuration
366 (e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with
367 one of the following commands.
369 On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and
370 derivatives) issue the following commands::
372 sudo ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/
373 sudo systemctl enable nginx
375 On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the
378 sudo ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/
379 sudo systemctl enable nginx
381 You can modify these commands and locations depending on your preferences and
382 the existing configuration of your nginx instance. The contents of
383 this ``nginx.conf`` file should be modeled on the following::
386 #################################################
387 # Stock useful config options, but ignore them :)
388 #################################################
389 include /etc/nginx/mime.types;
392 default_type application/octet-stream;
397 gzip_min_length 1024;
399 gzip_types text/plain application/x-javascript text/javascript text/xml text/css;
401 #####################################
402 # Mounting MediaGoblin stuff
403 # This is the section you should read
404 #####################################
406 # Change this to update the upload size limit for your users
407 client_max_body_size 8m;
409 # prevent attacks (someone uploading a .txt file that the browser
410 # interprets as an HTML file, etc.)
411 add_header X-Content-Type-Options nosniff;
413 server_name mediagoblin.example.org www.mediagoblin.example.org;
414 access_log /var/log/nginx/mediagoblin.example.access.log;
415 error_log /var/log/nginx/mediagoblin.example.error.log;
417 # MediaGoblin's stock static files: CSS, JS, etc.
418 location /mgoblin_static/ {
419 alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/;
422 # Instance specific media:
423 location /mgoblin_media/ {
424 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/;
427 # Theme static files (usually symlinked in)
428 location /theme_static/ {
429 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/theme_static/;
432 # Plugin static files (usually symlinked in)
433 location /plugin_static/ {
434 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/;
437 # Mounting MediaGoblin itself via FastCGI.
439 fastcgi_pass 127.0.0.1:26543;
440 include /etc/nginx/fastcgi_params;
442 # our understanding vs nginx's handling of script_name vs
443 # path_info don't match :)
444 fastcgi_param PATH_INFO $fastcgi_script_name;
445 fastcgi_param SCRIPT_NAME "";
449 The first four ``location`` directives instruct Nginx to serve the
450 static and uploaded files directly rather than through the MediaGoblin
451 process. This approach is faster and requires less memory.
455 The user who owns the Nginx process, normally ``www-data`` or ``nginx``,
456 requires execute permission on the directories ``static``,
457 ``public``, ``theme_static`` and ``plugin_static`` plus all their
458 parent directories. This user also requires read permission on all
459 the files within these directories. This is normally the default.
461 Nginx is now configured to serve the MediaGoblin application. Perform a quick
462 test to ensure that this configuration works::
466 If you encounter any errors, review your nginx configuration files, and try to
467 resolve them. If you do not encounter any errors, you can start your nginx
468 server with one of the following commands (depending on your environment)::
470 sudo /etc/init.d/nginx restart
471 sudo /etc/rc.d/nginx restart
472 sudo systemctl restart nginx
474 Now start MediaGoblin. Use the following command sequence as an
477 cd /srv/mediagoblin.example.org/mediagoblin/
478 su mediagoblin -s /bin/bash
479 ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
481 Visit the site you've set up in your browser by visiting
482 <http://mediagoblin.example.org>. You should see MediaGoblin!
486 The configuration described above is sufficient for development and
487 smaller deployments. However, for larger production deployments
488 with larger processing requirements, see the
489 ":doc:`production-deployments`" documentation.
495 Instructions and scripts for running MediaGoblin on an Apache server
496 can be found on the `MediaGoblin wiki <http://wiki.mediagoblin.org/Deployment>`_.
499 Security Considerations
500 ~~~~~~~~~~~~~~~~~~~~~~~
504 The directory ``user_dev/crypto/`` contains some very
506 Especially the ``itsdangeroussecret.bin`` is very important
507 for session security. Make sure not to leak its contents anywhere.
508 If the contents gets leaked nevertheless, delete your file
509 and restart the server, so that it creates a new secret key.
510 All previous sessions will be invalidated.