Move ./bootstrap.sh to experimental-bootstrap.sh
[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 -A -D mediagoblin
95
96 then create the database all our MediaGoblin data should be stored in::
97
98     sudo -u postgres createdb -E UNICODE -O mediagoblin mediagoblin
99
100 where the first ``mediagoblin`` is the database owner and the second
101 ``mediagoblin`` is the database name.
102
103 .. caution:: Where is the password?
104
105     These steps enable you to authenticate to the database in a password-less
106     manner via local UNIX authentication provided you run the MediaGoblin
107     application as a user with the same name as the user you created in
108     PostgreSQL.
109
110     More on this in :ref:`Drop Privileges for MediaGoblin <drop-privileges-for-mediagoblin>`.
111
112
113 .. _drop-privileges-for-mediagoblin:
114
115 Drop Privileges for MediaGoblin
116 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
117
118 MediaGoblin does not require special permissions or elevated
119 access to run. As such, the preferred way to run MediaGoblin is to
120 create a dedicated, unprivileged system user for the sole purpose of running
121 MediaGoblin. Running MediaGoblin processes under an unpriviledged system user
122 helps to keep it more secure. 
123
124 The following command (entered as root or with sudo) will create a
125 system account with a username of ``mediagoblin``. You may choose a different
126 username if you wish.::
127
128    adduser --system mediagoblin
129
130 No password will be assigned to this account, and you will not be able
131 to log in as this user. To switch to this account, enter either::
132
133   sudo -u mediagoblin /bin/bash  # (if you have sudo permissions)
134
135 or::
136
137   su mediagoblin -s /bin/bash  # (if you have to use root permissions)
138
139 You may get a warning similar to this when entering these commands::
140
141   warning: cannot change directory to /home/mediagoblin: No such file or directory
142
143 You can disregard this warning. To return to your regular user account after
144 using the system account, just enter ``exit``.
145
146 .. note::
147
148     Unless otherwise noted, the remainder of this document assumes that all
149     operations are performed using this unpriviledged account.
150
151 .. _create-mediagoblin-directory:
152
153 Create a MediaGoblin Directory
154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
155
156 You should create a working directory for MediaGoblin. This document
157 assumes your local git repository will be located at 
158 ``/srv/mediagoblin.example.org/mediagoblin/``.
159 Substitute your prefered local deployment path as needed.
160
161 Setting up the working directory requires that we first create the directory
162 with elevated priviledges, and then assign ownership of the directory
163 to the unpriviledged system account.
164
165 To do this, enter either of the following commands, changing the defaults
166 to suit your particular requirements::
167
168   sudo mkdir -p /srv/mediagoblin.example.org && sudo chown -hR mediagoblin:mediagoblin /srv/mediagoblin.example.org
169
170 or (as the root user)::
171
172   mkdir -p /srv/mediagoblin.example.org && chown -hR mediagoblin:mediagoblin /srv/mediagoblin.example.org
173
174
175 Install MediaGoblin and Virtualenv
176 ----------------------------------
177
178 .. note::
179
180    MediaGoblin is still developing rapidly. As a result
181    the following instructions recommend installing from the ``master``
182    branch of the git repository. Eventually production deployments will
183    want to transition to running from more consistent releases.
184
185 We will now clone the MediaGoblin source code repository and setup and
186 configure the necessary services. Modify these commands to
187 suit your own environment. As a reminder, you should enter these
188 commands using your unpriviledged system account.
189
190 Change to the MediaGoblin directory that you just created::
191
192     cd /srv/mediagoblin.example.org
193
194 Clone the MediaGoblin repository and set up the git submodules::
195
196     git clone git://gitorious.org/mediagoblin/mediagoblin.git
197     cd mediagoblin
198     git submodule init && git submodule update
199
200
201 And set up the in-package virtualenv::
202
203     (virtualenv --system-site-packages . || virtualenv .) && ./bin/python setup.py develop
204
205 .. note::
206
207    We presently have an **experimental** make-style deployment system.  if
208    you'd like to try it, instead of the above command, you can run::
209
210      ./experimental-bootstrap.sh && ./configure && make
211
212    This also includes a number of nice features, such as keeping your
213    viratualenv up to date by simply running `make update`.
214
215    Note: this is liable to break.  Use this method with caution.
216
217 .. ::
218
219    (NOTE: Is this still relevant?)
220
221    If you have problems here, consider trying to install virtualenv
222    with the ``--distribute`` or ``--no-site-packages`` options. If
223    your system's default Python is in the 3.x series you may need to
224    run ``virtualenv`` with the  ``--python=python2.7`` or
225    ``--python=python2.6`` options.
226
227 The above provides an in-package install of ``virtualenv``. While this
228 is counter to the conventional ``virtualenv`` configuration, it is
229 more reliable and considerably easier to configure and illustrate. If
230 you're familiar with Python packaging you may consider deploying with
231 your preferred method.
232
233 Assuming you are going to deploy with FastCGI, you should also install
234 flup::
235
236     ./bin/easy_install flup
237
238 (Sometimes this breaks because flup's site is flakey.  If it does for
239 you, try)::
240
241     ./bin/easy_install https://pypi.python.org/pypi/flup/1.0.3.dev-20110405
242
243 This concludes the initial configuration of the development
244 environment. In the future, when you update your
245 codebase, you should also run::
246
247     ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate && git submodule fetch
248
249 Note: If you are running an active site, depending on your server
250 configuration, you may need to stop it first or the dbupdate command
251 may hang (and it's certainly a good idea to restart it after the
252 update)
253
254
255 Deploy MediaGoblin Services
256 ---------------------------
257
258 Edit site configuration
259 ~~~~~~~~~~~~~~~~~~~~~~~
260
261 A few basic properties must be set before MediaGoblin will work. First
262 make a copy of ``mediagoblin.ini`` for editing so the original config
263 file isn't lost::
264
265     cp mediagoblin.ini mediagoblin_local.ini
266
267 Then:
268  - Set ``email_sender_address`` to the address you wish to be used as
269    the sender for system-generated emails
270  - Edit ``direct_remote_path``, ``base_dir``, and ``base_url`` if
271    your mediagoblin directory is not the root directory of your
272    vhost.
273
274
275 Configure MediaGoblin to use the PostgreSQL database
276 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
277
278 If you are using postgres, edit the ``[mediagoblin]`` section in your
279 ``mediagoblin_local.ini`` and put in::
280
281     sql_engine = postgresql:///mediagoblin
282
283 if you are running the MediaGoblin application as the same 'user' as the
284 database owner.
285
286
287 Update database data structures
288 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
289
290 Before you start using the database, you need to run::
291
292     ./bin/gmg dbupdate
293
294 to populate the database with the MediaGoblin data structures.
295
296
297 Test the Server
298 ~~~~~~~~~~~~~~~
299
300 At this point MediaGoblin should be properly installed.  You can
301 test the deployment with the following command::
302
303     ./lazyserver.sh --server-name=broadcast
304
305 You should be able to connect to the machine on port 6543 in your
306 browser to confirm that the service is operable.
307
308 .. _webserver-config:
309
310
311 FastCGI and nginx
312 ~~~~~~~~~~~~~~~~~
313
314 This configuration example will use nginx, however, you may
315 use any webserver of your choice as long as it supports the FastCGI
316 protocol. If you do not already have a web server, consider nginx, as
317 the configuration files may be more clear than the
318 alternatives.
319
320 Create a configuration file at
321 ``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link
322 into a directory that will be included in your ``nginx`` configuration
323 (e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with
324 one of the following commands (as the root user)::
325
326     ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/
327     ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/
328
329 Modify these commands and locations depending on your preferences and
330 the existing configuration of your nginx instance. The contents of
331 this ``nginx.conf`` file should be modeled on the following::
332
333     server {
334      #################################################
335      # Stock useful config options, but ignore them :)
336      #################################################
337      include /etc/nginx/mime.types;
338
339      autoindex off;
340      default_type  application/octet-stream;
341      sendfile on;
342
343      # Gzip
344      gzip on;
345      gzip_min_length 1024;
346      gzip_buffers 4 32k;
347      gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css;
348
349      #####################################
350      # Mounting MediaGoblin stuff
351      # This is the section you should read
352      #####################################
353
354      # Change this to update the upload size limit for your users
355      client_max_body_size 8m;
356
357      # prevent attacks (someone uploading a .txt file that the browser
358      # interprets as an HTML file, etc.)
359      add_header X-Content-Type-Options nosniff;
360
361      server_name mediagoblin.example.org www.mediagoblin.example.org;
362      access_log /var/log/nginx/mediagoblin.example.access.log;
363      error_log /var/log/nginx/mediagoblin.example.error.log;
364
365      # MediaGoblin's stock static files: CSS, JS, etc.
366      location /mgoblin_static/ {
367         alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/;
368      }
369
370      # Instance specific media:
371      location /mgoblin_media/ {
372         alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/;
373      }
374
375      # Theme static files (usually symlinked in)
376      location /theme_static/ {
377         alias /srv/mediagoblin.example.org/mediagoblin/user_dev/theme_static/;
378      }
379
380      # Plugin static files (usually symlinked in)
381      location /plugin_static/ {
382         alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/;
383      }
384
385      # Mounting MediaGoblin itself via FastCGI.
386      location / {
387         fastcgi_pass 127.0.0.1:26543;
388         include /etc/nginx/fastcgi_params;
389
390         # our understanding vs nginx's handling of script_name vs
391         # path_info don't match :)
392         fastcgi_param PATH_INFO $fastcgi_script_name;
393         fastcgi_param SCRIPT_NAME "";
394      }
395     }
396
397 Now, nginx instance is configured to serve the MediaGoblin
398 application. Perform a quick test to ensure that this configuration
399 works. Restart nginx so it picks up your changes, with a command that
400 resembles one of the following (as the root user)::
401
402     sudo /etc/init.d/nginx restart
403     sudo /etc/rc.d/nginx restart
404
405 Now start MediaGoblin. Use the following command sequence as an
406 example::
407
408     cd /srv/mediagoblin.example.org/mediagoblin/
409     ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
410
411 Visit the site you've set up in your browser by visiting
412 <http://mediagoblin.example.org>. You should see MediaGoblin!
413
414 .. note::
415
416    The configuration described above is sufficient for development and
417    smaller deployments. However, for larger production deployments
418    with larger processing requirements, see the
419    ":doc:`production-deployments`" documentation.
420    
421
422 Apache
423 ~~~~~~
424
425 Instructions and scripts for running MediaGoblin on an Apache server
426 can be found on the `MediaGoblin wiki <http://wiki.mediagoblin.org/Deployment>`_.
427
428
429 Security Considerations
430 ~~~~~~~~~~~~~~~~~~~~~~~
431
432 .. warning::
433
434    The directory ``user_dev/crypto/`` contains some very
435    sensitive files.
436    Especially the ``itsdangeroussecret.bin`` is very important
437    for session security. Make sure not to leak its contents anywhere.
438    If the contents gets leaked nevertheless, delete your file
439    and restart the server, so that it creates a new secret key.
440    All previous sessions will be invalidated.
441