Changing "su -" to just "su"... considerably simpler.
[mediagoblin:npigeons-mediagoblin.git] / docs / source / siteadmin / deploying.rst
1 .. MediaGoblin Documentation
2
3    Written in 2011, 2012, 2013 by MediaGoblin contributors
4
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
8    any warranty.
9
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/>.
13
14 .. _deploying-chapter:
15
16 =====================
17 Deploying MediaGoblin
18 =====================
19
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.
23
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
27 GNU/Linux distro.
28
29 .. note::
30
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.
34
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>`_.
39
40 Prepare System
41 --------------
42
43 Dependencies
44 ~~~~~~~~~~~~
45
46 MediaGoblin has the following core dependencies:
47
48 - Python 2.6 or 2.7
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
55 On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and
56 derivatives) issue the following command::
57
58     sudo apt-get install git-core python python-dev python-lxml \
59         python-imaging python-virtualenv
60
61 On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the
62 following command::
63
64     yum install python-paste-deploy python-paste-script \
65         git-core python python-devel python-lxml python-imaging \
66         python-virtualenv
67
68 Configure PostgreSQL
69 ~~~~~~~~~~~~~~~~~~~~
70
71 .. note::
72
73    MediaGoblin currently supports PostgreSQL and SQLite. The default is a
74    local SQLite database. This will "just work" for small deployments.
75
76    For medium to large deployments we recommend PostgreSQL.
77
78    If you don't want/need postgres, skip this section.
79
80 These are the packages needed for Debian Wheezy (stable)::
81
82     sudo apt-get install postgresql postgresql-client python-psycopg2
83
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.
88
89 In this example, the database user will be ``mediagoblin`` and the database
90 name will be ``mediagoblin`` too.
91
92 To create our new user, run::
93
94     sudo -u postgres createuser mediagoblin
95
96 then answer NO to *all* the questions::
97
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
101
102 then create the database all our MediaGoblin data should be stored in::
103
104     sudo -u postgres createdb -E UNICODE -O mediagoblin mediagoblin
105
106 where the first ``mediagoblin`` is the database owner and the second
107 ``mediagoblin`` is the database name.
108
109 .. caution:: Where is the password?
110
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
114     PostgreSQL.
115
116     More on this in :ref:`Drop Privileges for MediaGoblin <drop-privileges-for-mediagoblin>`.
117
118
119 .. _drop-privileges-for-mediagoblin:
120
121 Drop Privileges for MediaGoblin
122 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
123
124 MediaGoblin does not require special permissions or elevated
125 access to run. As such, the preferred way to run MediaGoblin is to
126 create a dedicated, unprivileged system user for the sole purpose of running
127 MediaGoblin. Running MediaGoblin processes under an unpriviledged system user
128 helps to keep it more secure. 
129
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.::
133
134    adduser --system mediagoblin
135
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::
138
139   sudo su mediagoblin  # (if you have sudo permissions)
140
141 or::
142
143   su mediagoblin  # (if you have to use root permissions)
144
145 You may get a warning similar to this when entering these commands::
146
147   warning: cannot change directory to /home/mediagoblin: No such file or directory
148
149 You can disregard this warning. To return to your regular user account after
150 using the system account, just enter ``exit``.
151
152 .. note::
153
154     Unless otherwise noted, the remainder of this document assumes that all
155     operations are performed using this unpriviledged account.
156
157 .. _create-mediagoblin-directory:
158
159 Create a MediaGoblin Directory
160 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
161
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.
166
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.
170
171 To do this, enter either of the following commands, changing the defaults
172 to suit your particular requirements::
173
174   sudo mkdir -p /srv/mediagoblin.example.org && sudo chown -hR mediagoblin:mediagoblin /srv/mediagoblin.example.org
175
176 or (as the root user)::
177
178   mkdir -p /srv/mediagoblin.example.org && chown -hR mediagoblin:mediagoblin /srv/mediagoblin.example.org
179
180
181 Install MediaGoblin and Virtualenv
182 ----------------------------------
183
184 .. note::
185
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.
190
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.
195
196 Change to the MediaGoblin directory that you just created::
197
198     cd /srv/mediagoblin.example.org
199
200 Clone the MediaGoblin repository and set up the git submodules::
201
202     git clone git://gitorious.org/mediagoblin/mediagoblin.git
203     cd mediagoblin
204     git submodule init && git submodule update
205
206
207 And set up the in-package virtualenv::
208
209     (virtualenv --system-site-packages . || virtualenv .) && ./bin/python setup.py develop
210
211 .. note::
212
213    We presently have an experimental make-style deployment system.  if
214    you'd like to try it, instead of the above command, you can run::
215
216      ./bootstrap.sh && ./configure && make
217
218    This also includes a number of nice features, such as keeping your
219    viratualenv up to date by simply running `make update`.
220
221 .. ::
222
223    (NOTE: Is this still relevant?)
224
225    If you have problems here, consider trying to install virtualenv
226    with the ``--distribute`` or ``--no-site-packages`` options. If
227    your system's default Python is in the 3.x series you may need to
228    run ``virtualenv`` with the  ``--python=python2.7`` or
229    ``--python=python2.6`` options.
230
231 The above provides an in-package install of ``virtualenv``. While this
232 is counter to the conventional ``virtualenv`` configuration, it is
233 more reliable and considerably easier to configure and illustrate. If
234 you're familiar with Python packaging you may consider deploying with
235 your preferred method.
236
237 Assuming you are going to deploy with FastCGI, you should also install
238 flup::
239
240     ./bin/easy_install flup
241
242 (Sometimes this breaks because flup's site is flakey.  If it does for
243 you, try)::
244
245     ./bin/easy_install https://pypi.python.org/pypi/flup/1.0.3.dev-20110405
246
247 This concludes the initial configuration of the development
248 environment. In the future, when you update your
249 codebase, you should also run::
250
251     ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate && git submodule fetch
252
253 Note: If you are running an active site, depending on your server
254 configuration, you may need to stop it first or the dbupdate command
255 may hang (and it's certainly a good idea to restart it after the
256 update)
257
258
259 Deploy MediaGoblin Services
260 ---------------------------
261
262 Edit site configuration
263 ~~~~~~~~~~~~~~~~~~~~~~~
264
265 A few basic properties must be set before MediaGoblin will work. First
266 make a copy of ``mediagoblin.ini`` for editing so the original config
267 file isn't lost::
268
269     cp mediagoblin.ini mediagoblin_local.ini
270
271 Then:
272  - Set ``email_sender_address`` to the address you wish to be used as
273    the sender for system-generated emails
274  - Edit ``direct_remote_path``, ``base_dir``, and ``base_url`` if
275    your mediagoblin directory is not the root directory of your
276    vhost.
277
278
279 Configure MediaGoblin to use the PostgreSQL database
280 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
281
282 If you are using postgres, edit the ``[mediagoblin]`` section in your
283 ``mediagoblin_local.ini`` and put in::
284
285     sql_engine = postgresql:///mediagoblin
286
287 if you are running the MediaGoblin application as the same 'user' as the
288 database owner.
289
290
291 Update database data structures
292 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
293
294 Before you start using the database, you need to run::
295
296     ./bin/gmg dbupdate
297
298 to populate the database with the MediaGoblin data structures.
299
300
301 Test the Server
302 ~~~~~~~~~~~~~~~
303
304 At this point MediaGoblin should be properly installed.  You can
305 test the deployment with the following command::
306
307     ./lazyserver.sh --server-name=broadcast
308
309 You should be able to connect to the machine on port 6543 in your
310 browser to confirm that the service is operable.
311
312 .. _webserver-config:
313
314
315 FastCGI and nginx
316 ~~~~~~~~~~~~~~~~~
317
318 This configuration example will use nginx, however, you may
319 use any webserver of your choice as long as it supports the FastCGI
320 protocol. If you do not already have a web server, consider nginx, as
321 the configuration files may be more clear than the
322 alternatives.
323
324 Create a configuration file at
325 ``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link
326 into a directory that will be included in your ``nginx`` configuration
327 (e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with
328 one of the following commands (as the root user)::
329
330     ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/
331     ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/
332
333 Modify these commands and locations depending on your preferences and
334 the existing configuration of your nginx instance. The contents of
335 this ``nginx.conf`` file should be modeled on the following::
336
337     server {
338      #################################################
339      # Stock useful config options, but ignore them :)
340      #################################################
341      include /etc/nginx/mime.types;
342
343      autoindex off;
344      default_type  application/octet-stream;
345      sendfile on;
346
347      # Gzip
348      gzip on;
349      gzip_min_length 1024;
350      gzip_buffers 4 32k;
351      gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css;
352
353      #####################################
354      # Mounting MediaGoblin stuff
355      # This is the section you should read
356      #####################################
357
358      # Change this to update the upload size limit for your users
359      client_max_body_size 8m;
360
361      # prevent attacks (someone uploading a .txt file that the browser
362      # interprets as an HTML file, etc.)
363      add_header X-Content-Type-Options nosniff;
364
365      server_name mediagoblin.example.org www.mediagoblin.example.org;
366      access_log /var/log/nginx/mediagoblin.example.access.log;
367      error_log /var/log/nginx/mediagoblin.example.error.log;
368
369      # MediaGoblin's stock static files: CSS, JS, etc.
370      location /mgoblin_static/ {
371         alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/;
372      }
373
374      # Instance specific media:
375      location /mgoblin_media/ {
376         alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/;
377      }
378
379      # Theme static files (usually symlinked in)
380      location /theme_static/ {
381         alias /srv/mediagoblin.example.org/mediagoblin/user_dev/theme_static/;
382      }
383
384      # Plugin static files (usually symlinked in)
385      location /plugin_static/ {
386         alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/;
387      }
388
389      # Mounting MediaGoblin itself via FastCGI.
390      location / {
391         fastcgi_pass 127.0.0.1:26543;
392         include /etc/nginx/fastcgi_params;
393
394         # our understanding vs nginx's handling of script_name vs
395         # path_info don't match :)
396         fastcgi_param PATH_INFO $fastcgi_script_name;
397         fastcgi_param SCRIPT_NAME "";
398      }
399     }
400
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)::
405
406     sudo /etc/init.d/nginx restart
407     sudo /etc/rc.d/nginx restart
408
409 Now start MediaGoblin. Use the following command sequence as an
410 example::
411
412     cd /srv/mediagoblin.example.org/mediagoblin/
413     ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
414
415 Visit the site you've set up in your browser by visiting
416 <http://mediagoblin.example.org>. You should see MediaGoblin!
417
418 .. note::
419
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.
424    
425
426 Apache
427 ~~~~~~
428
429 Instructions and scripts for running MediaGoblin on an Apache server
430 can be found on the `MediaGoblin wiki <http://wiki.mediagoblin.org/Deployment>`_.
431
432
433 Security Considerations
434 ~~~~~~~~~~~~~~~~~~~~~~~
435
436 .. warning::
437
438    The directory ``user_dev/crypto/`` contains some very
439    sensitive files.
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.
445