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/>`_
54 - `nodejs <https://nodejs.org>`_
56 On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and
57 derivatives) issue the following command::
59 # apt-get install git-core python python-dev python-lxml \
60 python-imaging python-virtualenv npm automake
62 On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the
65 # yum install python-paste-deploy python-paste-script \
66 git-core python python-devel python-lxml python-imaging \
67 python-virtualenv npm automake
74 MediaGoblin currently supports PostgreSQL and SQLite. The default is a
75 local SQLite database. This will "just work" for small deployments.
77 For medium to large deployments we recommend PostgreSQL.
79 If you don't want/need postgres, skip this section.
81 These are the packages needed for Debian Wheezy (stable)::
83 # apt-get install postgresql postgresql-client python-psycopg2
85 These are the packages needed for an RPM-based system::
87 # yum install postgresql postgresql-server python-psycopg2
89 An RPM-based system also requires that you initialize the PostgresSQL database
90 with this command. The following command is not needed on a Debian-based
93 # /usr/bin/postgresql-setup initdb
95 The installation process will create a new *system* user named ``postgres``,
96 which will have privilegies sufficient to manage the database. We will create a
97 new database user with restricted privilegies and a new database owned by our
98 restricted database user for our MediaGoblin instance.
100 In this example, the database user will be ``mediagoblin`` and the database
101 name will be ``mediagoblin`` too.
103 We'll add these entities by first switching to the *postgres* account::
107 This will change your prompt to a shell prompt, such as *-bash-4.2$*. Enter
108 the following *createuser* and *createdb* commands at that prompt. We'll
109 create the *mediagoblin* database user first::
111 $ createuser -A -D mediagoblin
113 Then we'll create the database where all of our MediaGoblin data will be stored::
115 $ createdb -E UNICODE -O mediagoblin mediagoblin
117 where the first ``mediagoblin`` is the database owner and the second
118 ``mediagoblin`` is the database name.
120 Type ``exit`` to return to the *root* user prompt. From here we just need to
121 set the Postgres database to start on boot, and also start it up for this
122 particular session. If you're on a platform that does not use *systemd*, you
125 # chkconfig postgresql on && service postgresql start
127 Whereas users of *systemd*-based systems will need to enter::
129 # systemctl enable postgresql && systemctl start postgresql
131 .. caution:: Where is the password?
133 These steps enable you to authenticate to the database in a password-less
134 manner via local UNIX authentication provided you run the MediaGoblin
135 application as a user with the same name as the user you created in
138 More on this in :ref:`Drop Privileges for MediaGoblin <drop-privileges-for-mediagoblin>`.
141 .. _drop-privileges-for-mediagoblin:
143 Drop Privileges for MediaGoblin
144 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
146 MediaGoblin does not require special permissions or elevated
147 access to run. As such, the preferred way to run MediaGoblin is to
148 create a dedicated, unprivileged system user for the sole purpose of running
149 MediaGoblin. Running MediaGoblin processes under an unpriviledged system user
150 helps to keep it more secure.
152 The following command (entered as root or with sudo) will create a
153 system account with a username of ``mediagoblin``. You may choose a different
154 username if you wish.::
156 # useradd --system --user-group mediagoblin
158 No password will be assigned to this account, and you will not be able
159 to log in as this user. To switch to this account, enter::
161 su mediagoblin -s /bin/bash # (if you have to use root permissions)
163 You may get a warning similar to this when entering these commands::
165 warning: cannot change directory to /home/mediagoblin: No such file or directory
167 You can disregard this warning. To return to your regular user account after
168 using the system account, just enter ``exit``.
170 .. _create-mediagoblin-directory:
172 Create a MediaGoblin Directory
173 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
175 You should create a working directory for MediaGoblin. This document
176 assumes your local git repository will be located at
177 ``/srv/mediagoblin.example.org/mediagoblin/``.
178 Substitute your prefered local deployment path as needed.
180 Setting up the working directory requires that we first create the directory
181 with elevated priviledges, and then assign ownership of the directory
182 to the unpriviledged system account.
184 To do this, enter either of the following commands, changing the defaults
185 to suit your particular requirements::
187 # mkdir -p /srv/mediagoblin.example.org && sudo chown -hR mediagoblin: /srv/mediagoblin.example.org
191 Unless otherwise noted, the remainder of this document assumes that all
192 operations are performed using this unpriviledged account.
195 Install MediaGoblin and Virtualenv
196 ----------------------------------
198 We will now clone the MediaGoblin source code repository and setup and
199 configure the necessary services. Modify these commands to
200 suit your own environment.
204 As a reminder, you should enter these commands using your unpriviledged
205 *mediagoblin* system account.
207 Change to the MediaGoblin directory that you just created::
209 $ cd /srv/mediagoblin.example.org
211 Clone the MediaGoblin repository and set up the git submodules::
213 $ git clone https://gitorious.org/mediagoblin/mediagoblin.git -b stable
215 $ git submodule init && git submodule update
218 Set up the hacking environment::
220 $ ./bootstrap.sh && ./configure && make
222 The above provides an in-package install of ``virtualenv``. While this
223 is counter to the conventional ``virtualenv`` configuration, it is
224 more reliable and considerably easier to configure and illustrate. If
225 you're familiar with Python packaging you may consider deploying with
226 your preferred method.
228 Assuming you are going to deploy with FastCGI, you should also install
231 $ ./bin/easy_install flup
233 This concludes the initial configuration of the development
234 environment. In the future, when you update your
235 codebase, you should also run::
237 $ git submodule update && ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate
241 Note: If you are running an active site, depending on your server
242 configuration, you may need to stop it first or the dbupdate command
243 may hang (and it's certainly a good idea to restart it after the
247 Deploy MediaGoblin Services
248 ---------------------------
250 Edit site configuration
251 ~~~~~~~~~~~~~~~~~~~~~~~
253 A few basic properties must be set before MediaGoblin will work. First
254 make a copy of ``mediagoblin.ini`` for editing so the original config
257 cp mediagoblin.ini mediagoblin_local.ini
260 - Set ``email_sender_address`` to the address you wish to be used as
261 the sender for system-generated emails
262 - Edit ``direct_remote_path``, ``base_dir``, and ``base_url`` if
263 your mediagoblin directory is not the root directory of your
267 Configure MediaGoblin to use the PostgreSQL database
268 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
270 If you are using postgres, edit the ``[mediagoblin]`` section in your
271 ``mediagoblin_local.ini`` and put in::
273 sql_engine = postgresql:///mediagoblin
275 if you are running the MediaGoblin application as the same 'user' as the
279 Update database data structures
280 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
282 Before you start using the database, you need to run::
286 to populate the database with the MediaGoblin data structures.
292 At this point MediaGoblin should be properly installed. You can
293 test the deployment with the following command::
295 ./lazyserver.sh --server-name=broadcast
297 You should be able to connect to the machine on port 6543 in your
298 browser to confirm that the service is operable.
300 .. _webserver-config:
306 This configuration example will use nginx, however, you may
307 use any webserver of your choice as long as it supports the FastCGI
308 protocol. If you do not already have a web server, consider nginx, as
309 the configuration files may be more clear than the
312 Create a configuration file at
313 ``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link
314 into a directory that will be included in your ``nginx`` configuration
315 (e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with
316 one of the following commands (as the root user)::
318 ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/
319 ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/
321 Modify these commands and locations depending on your preferences and
322 the existing configuration of your nginx instance. The contents of
323 this ``nginx.conf`` file should be modeled on the following::
326 #################################################
327 # Stock useful config options, but ignore them :)
328 #################################################
329 include /etc/nginx/mime.types;
332 default_type application/octet-stream;
337 gzip_min_length 1024;
339 gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css;
341 #####################################
342 # Mounting MediaGoblin stuff
343 # This is the section you should read
344 #####################################
346 # Change this to update the upload size limit for your users
347 client_max_body_size 8m;
349 # prevent attacks (someone uploading a .txt file that the browser
350 # interprets as an HTML file, etc.)
351 add_header X-Content-Type-Options nosniff;
353 server_name mediagoblin.example.org www.mediagoblin.example.org;
354 access_log /var/log/nginx/mediagoblin.example.access.log;
355 error_log /var/log/nginx/mediagoblin.example.error.log;
357 # MediaGoblin's stock static files: CSS, JS, etc.
358 location /mgoblin_static/ {
359 alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/;
362 # Instance specific media:
363 location /mgoblin_media/ {
364 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/;
367 # Theme static files (usually symlinked in)
368 location /theme_static/ {
369 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/theme_static/;
372 # Plugin static files (usually symlinked in)
373 location /plugin_static/ {
374 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/;
377 # Mounting MediaGoblin itself via FastCGI.
379 fastcgi_pass 127.0.0.1:26543;
380 include /etc/nginx/fastcgi_params;
382 # our understanding vs nginx's handling of script_name vs
383 # path_info don't match :)
384 fastcgi_param PATH_INFO $fastcgi_script_name;
385 fastcgi_param SCRIPT_NAME "";
389 The first four ``location`` directives instruct Nginx to serve the
390 static and uploaded files directly rather than through the MediaGoblin
391 process. This approach is faster and requires less memory.
395 The user who owns the Nginx process, normally ``www-data``,
396 requires execute permission on the directories ``static``,
397 ``public``, ``theme_static`` and ``plugin_static`` plus all their
398 parent directories. This user also requires read permission on all
399 the files within these directories. This is normally the default.
401 Now, nginx instance is configured to serve the MediaGoblin
402 application. Perform a quick test to ensure that this configuration
403 works. Restart nginx so it picks up your changes, with a command that
404 resembles one of the following (as the root user)::
406 sudo /etc/init.d/nginx restart
407 sudo /etc/rc.d/nginx restart
409 Now start MediaGoblin. Use the following command sequence as an
412 cd /srv/mediagoblin.example.org/mediagoblin/
413 ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
415 Visit the site you've set up in your browser by visiting
416 <http://mediagoblin.example.org>. You should see MediaGoblin!
420 The configuration described above is sufficient for development and
421 smaller deployments. However, for larger production deployments
422 with larger processing requirements, see the
423 ":doc:`production-deployments`" documentation.
429 Instructions and scripts for running MediaGoblin on an Apache server
430 can be found on the `MediaGoblin wiki <http://wiki.mediagoblin.org/Deployment>`_.
433 Security Considerations
434 ~~~~~~~~~~~~~~~~~~~~~~~
438 The directory ``user_dev/crypto/`` contains some very
440 Especially the ``itsdangeroussecret.bin`` is very important
441 for session security. Make sure not to leak its contents anywhere.
442 If the contents gets leaked nevertheless, delete your file
443 and restart the server, so that it creates a new secret key.
444 All previous sessions will be invalidated.