Commit | Line | Data |
---|---|---|
473a4431 CAW |
1 | .. MediaGoblin Documentation |
2 | ||
fd5c35e5 | 3 | Written in 2011, 2012, 2013 by MediaGoblin contributors |
473a4431 CAW |
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 | ||
abe74178 WKG |
14 | .. _deploying-chapter: |
15 | ||
4e893b6e | 16 | ===================== |
17 | Deploying MediaGoblin | |
18 | ===================== | |
00fdc7bd | 19 | |
e260065a CAW |
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. | |
56d507b6 | 23 | |
e260065a CAW |
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 | ||
076bf0cf WKG |
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. | |
e260065a | 34 | |
4d8a3cd8 CAW |
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 | ||
4e893b6e | 40 | Prepare System |
41 | -------------- | |
e260065a | 42 | |
4e893b6e | 43 | Dependencies |
44 | ~~~~~~~~~~~~ | |
e260065a | 45 | |
4e893b6e | 46 | MediaGoblin has the following core dependencies: |
e260065a | 47 | |
2acf47d8 | 48 | - Python 2.7 |
4e893b6e | 49 | - `python-lxml <http://lxml.de/>`_ |
50 | - `git <http://git-scm.com/>`_ | |
775ec9e8 | 51 | - `SQLite <http://www.sqlite.org/>`_/`PostgreSQL <http://www.postgresql.org/>`_ |
4e893b6e | 52 | - `Python Imaging Library <http://www.pythonware.com/products/pil/>`_ (PIL) |
53 | - `virtualenv <http://www.virtualenv.org/>`_ | |
4ec1af11 | 54 | - `nodejs <https://nodejs.org>`_ |
e260065a | 55 | |
4e893b6e | 56 | On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and |
7798f911 | 57 | derivatives) issue the following command:: |
e260065a | 58 | |
c3075e91 | 59 | # apt-get install git-core python python-dev python-lxml \ |
4ec1af11 | 60 | python-imaging python-virtualenv npm automake |
e260065a | 61 | |
4e893b6e | 62 | On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the |
7798f911 | 63 | following command:: |
4e893b6e | 64 | |
c3075e91 | 65 | # yum install python-paste-deploy python-paste-script \ |
076bf0cf | 66 | git-core python python-devel python-lxml python-imaging \ |
4ec1af11 | 67 | python-virtualenv npm automake |
e260065a | 68 | |
775ec9e8 JW |
69 | Configure PostgreSQL |
70 | ~~~~~~~~~~~~~~~~~~~~ | |
71 | ||
72 | .. note:: | |
73 | ||
7798f911 WKG |
74 | MediaGoblin currently supports PostgreSQL and SQLite. The default is a |
75 | local SQLite database. This will "just work" for small deployments. | |
775ec9e8 | 76 | |
7798f911 WKG |
77 | For medium to large deployments we recommend PostgreSQL. |
78 | ||
79 | If you don't want/need postgres, skip this section. | |
80 | ||
fd5c35e5 | 81 | These are the packages needed for Debian Wheezy (stable):: |
775ec9e8 | 82 | |
c3075e91 JC |
83 | # apt-get install postgresql postgresql-client python-psycopg2 |
84 | ||
85 | These are the packages needed for an RPM-based system:: | |
86 | ||
87 | # yum install postgresql postgresql-server python-psycopg2 | |
88 | ||
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 | |
91 | platform, however:: | |
92 | ||
93 | # /usr/bin/postgresql-setup initdb | |
775ec9e8 JW |
94 | |
95 | The installation process will create a new *system* user named ``postgres``, | |
c3075e91 | 96 | which will have privilegies sufficient to manage the database. We will create a |
775ec9e8 JW |
97 | new database user with restricted privilegies and a new database owned by our |
98 | restricted database user for our MediaGoblin instance. | |
99 | ||
100 | In this example, the database user will be ``mediagoblin`` and the database | |
101 | name will be ``mediagoblin`` too. | |
102 | ||
c3075e91 JC |
103 | We'll add these entities by first switching to the *postgres* account:: |
104 | ||
105 | # su -u postgres | |
775ec9e8 | 106 | |
c3075e91 JC |
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:: | |
775ec9e8 | 110 | |
c3075e91 | 111 | $ createuser -A -D mediagoblin |
775ec9e8 | 112 | |
c3075e91 JC |
113 | Then we'll create the database where all of our MediaGoblin data will be stored:: |
114 | ||
115 | $ createdb -E UNICODE -O mediagoblin mediagoblin | |
775ec9e8 JW |
116 | |
117 | where the first ``mediagoblin`` is the database owner and the second | |
118 | ``mediagoblin`` is the database name. | |
119 | ||
c3075e91 JC |
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 | |
123 | can enter:: | |
124 | ||
125 | # chkconfig postgresql on && service postgresql start | |
126 | ||
127 | Whereas users of *systemd*-based systems will need to enter:: | |
128 | ||
129 | # systemctl enable postgresql && systemctl start postgresql | |
130 | ||
775ec9e8 JW |
131 | .. caution:: Where is the password? |
132 | ||
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 | |
136 | PostgreSQL. | |
137 | ||
138 | More on this in :ref:`Drop Privileges for MediaGoblin <drop-privileges-for-mediagoblin>`. | |
139 | ||
140 | ||
775ec9e8 JW |
141 | .. _drop-privileges-for-mediagoblin: |
142 | ||
4e893b6e | 143 | Drop Privileges for MediaGoblin |
144 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
17c71230 | 145 | |
fd5c35e5 | 146 | MediaGoblin does not require special permissions or elevated |
1b4a9f26 CAW |
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 | |
fd5c35e5 JC |
149 | MediaGoblin. Running MediaGoblin processes under an unpriviledged system user |
150 | helps to keep it more secure. | |
151 | ||
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.:: | |
155 | ||
6663dfa3 | 156 | useradd --system --user-group mediagoblin |
fd5c35e5 JC |
157 | |
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 either:: | |
160 | ||
f055b475 | 161 | sudo -u mediagoblin /bin/bash # (if you have sudo permissions) |
fd5c35e5 | 162 | |
9b604868 | 163 | or:: |
fd5c35e5 | 164 | |
f055b475 | 165 | su mediagoblin -s /bin/bash # (if you have to use root permissions) |
fd5c35e5 JC |
166 | |
167 | You may get a warning similar to this when entering these commands:: | |
168 | ||
9b604868 | 169 | warning: cannot change directory to /home/mediagoblin: No such file or directory |
fd5c35e5 JC |
170 | |
171 | You can disregard this warning. To return to your regular user account after | |
172 | using the system account, just enter ``exit``. | |
173 | ||
fd5c35e5 JC |
174 | .. _create-mediagoblin-directory: |
175 | ||
176 | Create a MediaGoblin Directory | |
177 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
17c71230 | 178 | |
4e893b6e | 179 | You should create a working directory for MediaGoblin. This document |
076bf0cf | 180 | assumes your local git repository will be located at |
fd5c35e5 JC |
181 | ``/srv/mediagoblin.example.org/mediagoblin/``. |
182 | Substitute your prefered local deployment path as needed. | |
183 | ||
184 | Setting up the working directory requires that we first create the directory | |
185 | with elevated priviledges, and then assign ownership of the directory | |
186 | to the unpriviledged system account. | |
17c71230 | 187 | |
fd5c35e5 JC |
188 | To do this, enter either of the following commands, changing the defaults |
189 | to suit your particular requirements:: | |
17c71230 | 190 | |
c3075e91 | 191 | # mkdir -p /srv/mediagoblin.example.org && sudo chown -hR mediagoblin: /srv/mediagoblin.example.org |
fd5c35e5 | 192 | |
c3075e91 | 193 | .. note:: |
fd5c35e5 | 194 | |
c3075e91 JC |
195 | Unless otherwise noted, the remainder of this document assumes that all |
196 | operations are performed using this unpriviledged account. | |
17c71230 | 197 | |
4e893b6e | 198 | |
e260065a | 199 | Install MediaGoblin and Virtualenv |
4e893b6e | 200 | ---------------------------------- |
e260065a | 201 | |
076bf0cf WKG |
202 | .. note:: |
203 | ||
7798f911 | 204 | MediaGoblin is still developing rapidly. As a result |
076bf0cf WKG |
205 | the following instructions recommend installing from the ``master`` |
206 | branch of the git repository. Eventually production deployments will | |
207 | want to transition to running from more consistent releases. | |
e260065a | 208 | |
fd5c35e5 JC |
209 | We will now clone the MediaGoblin source code repository and setup and |
210 | configure the necessary services. Modify these commands to | |
211 | suit your own environment. As a reminder, you should enter these | |
212 | commands using your unpriviledged system account. | |
17c71230 | 213 | |
fd5c35e5 JC |
214 | Change to the MediaGoblin directory that you just created:: |
215 | ||
216 | cd /srv/mediagoblin.example.org | |
17c71230 | 217 | |
d3b1fd2e | 218 | Clone the MediaGoblin repository and set up the git submodules:: |
e260065a | 219 | |
82be36d1 | 220 | git clone https://gitorious.org/mediagoblin/mediagoblin.git -b stable |
b889f971 | 221 | cd mediagoblin |
64ad0bee | 222 | git submodule init && git submodule update |
e260065a | 223 | |
e260065a | 224 | |
41dbb27a | 225 | Set up the hacking environment:: |
3b8251f3 | 226 | |
41dbb27a | 227 | ./bootstrap.sh && ./configure && make |
f0e137ab | 228 | |
4e893b6e | 229 | The above provides an in-package install of ``virtualenv``. While this |
230 | is counter to the conventional ``virtualenv`` configuration, it is | |
231 | more reliable and considerably easier to configure and illustrate. If | |
232 | you're familiar with Python packaging you may consider deploying with | |
c356dc16 | 233 | your preferred method. |
e260065a | 234 | |
076bf0cf WKG |
235 | Assuming you are going to deploy with FastCGI, you should also install |
236 | flup:: | |
99192f24 | 237 | |
076bf0cf | 238 | ./bin/easy_install flup |
99192f24 | 239 | |
71ef2007 CAW |
240 | (Sometimes this breaks because flup's site is flakey. If it does for |
241 | you, try):: | |
242 | ||
243 | ./bin/easy_install https://pypi.python.org/pypi/flup/1.0.3.dev-20110405 | |
244 | ||
4e893b6e | 245 | This concludes the initial configuration of the development |
8d9aa03f | 246 | environment. In the future, when you update your |
076bf0cf | 247 | codebase, you should also run:: |
e260065a | 248 | |
e99431cc | 249 | git submodule update && ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate |
e260065a | 250 | |
9d5cd0b9 CAW |
251 | Note: If you are running an active site, depending on your server |
252 | configuration, you may need to stop it first or the dbupdate command | |
253 | may hang (and it's certainly a good idea to restart it after the | |
254 | update) | |
255 | ||
256 | ||
4e893b6e | 257 | Deploy MediaGoblin Services |
258 | --------------------------- | |
e260065a | 259 | |
a7d2a892 ST |
260 | Edit site configuration |
261 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
262 | ||
041d2fd7 CAW |
263 | A few basic properties must be set before MediaGoblin will work. First |
264 | make a copy of ``mediagoblin.ini`` for editing so the original config | |
265 | file isn't lost:: | |
a7d2a892 ST |
266 | |
267 | cp mediagoblin.ini mediagoblin_local.ini | |
a7d2a892 | 268 | |
041d2fd7 CAW |
269 | Then: |
270 | - Set ``email_sender_address`` to the address you wish to be used as | |
271 | the sender for system-generated emails | |
272 | - Edit ``direct_remote_path``, ``base_dir``, and ``base_url`` if | |
273 | your mediagoblin directory is not the root directory of your | |
274 | vhost. | |
a7d2a892 ST |
275 | |
276 | ||
775ec9e8 JW |
277 | Configure MediaGoblin to use the PostgreSQL database |
278 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
279 | ||
7798f911 WKG |
280 | If you are using postgres, edit the ``[mediagoblin]`` section in your |
281 | ``mediagoblin_local.ini`` and put in:: | |
775ec9e8 JW |
282 | |
283 | sql_engine = postgresql:///mediagoblin | |
284 | ||
285 | if you are running the MediaGoblin application as the same 'user' as the | |
286 | database owner. | |
287 | ||
7798f911 | 288 | |
775ec9e8 JW |
289 | Update database data structures |
290 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
291 | ||
7798f911 | 292 | Before you start using the database, you need to run:: |
775ec9e8 JW |
293 | |
294 | ./bin/gmg dbupdate | |
295 | ||
296 | to populate the database with the MediaGoblin data structures. | |
297 | ||
298 | ||
4e893b6e | 299 | Test the Server |
300 | ~~~~~~~~~~~~~~~ | |
e260065a | 301 | |
4e893b6e | 302 | At this point MediaGoblin should be properly installed. You can |
076bf0cf | 303 | test the deployment with the following command:: |
e260065a | 304 | |
076bf0cf | 305 | ./lazyserver.sh --server-name=broadcast |
e260065a | 306 | |
4e893b6e | 307 | You should be able to connect to the machine on port 6543 in your |
308 | browser to confirm that the service is operable. | |
e260065a | 309 | |
cd1abb11 CAW |
310 | .. _webserver-config: |
311 | ||
56d507b6 | 312 | |
a7d2a892 ST |
313 | FastCGI and nginx |
314 | ~~~~~~~~~~~~~~~~~ | |
315 | ||
316 | This configuration example will use nginx, however, you may | |
4e893b6e | 317 | use any webserver of your choice as long as it supports the FastCGI |
318 | protocol. If you do not already have a web server, consider nginx, as | |
319 | the configuration files may be more clear than the | |
320 | alternatives. | |
321 | ||
322 | Create a configuration file at | |
323 | ``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link | |
324 | into a directory that will be included in your ``nginx`` configuration | |
325 | (e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with | |
076bf0cf | 326 | one of the following commands (as the root user):: |
4e893b6e | 327 | |
076bf0cf WKG |
328 | ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/ |
329 | ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/ | |
4e893b6e | 330 | |
331 | Modify these commands and locations depending on your preferences and | |
332 | the existing configuration of your nginx instance. The contents of | |
076bf0cf WKG |
333 | this ``nginx.conf`` file should be modeled on the following:: |
334 | ||
335 | server { | |
336 | ################################################# | |
337 | # Stock useful config options, but ignore them :) | |
338 | ################################################# | |
339 | include /etc/nginx/mime.types; | |
340 | ||
341 | autoindex off; | |
342 | default_type application/octet-stream; | |
343 | sendfile on; | |
344 | ||
345 | # Gzip | |
346 | gzip on; | |
347 | gzip_min_length 1024; | |
348 | gzip_buffers 4 32k; | |
349 | gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css; | |
350 | ||
351 | ##################################### | |
352 | # Mounting MediaGoblin stuff | |
353 | # This is the section you should read | |
354 | ##################################### | |
355 | ||
356 | # Change this to update the upload size limit for your users | |
357 | client_max_body_size 8m; | |
358 | ||
a49c741f CAW |
359 | # prevent attacks (someone uploading a .txt file that the browser |
360 | # interprets as an HTML file, etc.) | |
361 | add_header X-Content-Type-Options nosniff; | |
37b48053 | 362 | |
076bf0cf WKG |
363 | server_name mediagoblin.example.org www.mediagoblin.example.org; |
364 | access_log /var/log/nginx/mediagoblin.example.access.log; | |
365 | error_log /var/log/nginx/mediagoblin.example.error.log; | |
366 | ||
367 | # MediaGoblin's stock static files: CSS, JS, etc. | |
368 | location /mgoblin_static/ { | |
369 | alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/; | |
370 | } | |
371 | ||
372 | # Instance specific media: | |
373 | location /mgoblin_media/ { | |
374 | alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/; | |
375 | } | |
376 | ||
8d051cc0 CAW |
377 | # Theme static files (usually symlinked in) |
378 | location /theme_static/ { | |
379 | alias /srv/mediagoblin.example.org/mediagoblin/user_dev/theme_static/; | |
380 | } | |
381 | ||
24ede044 CAW |
382 | # Plugin static files (usually symlinked in) |
383 | location /plugin_static/ { | |
384 | alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/; | |
385 | } | |
386 | ||
076bf0cf WKG |
387 | # Mounting MediaGoblin itself via FastCGI. |
388 | location / { | |
389 | fastcgi_pass 127.0.0.1:26543; | |
390 | include /etc/nginx/fastcgi_params; | |
391 | ||
392 | # our understanding vs nginx's handling of script_name vs | |
393 | # path_info don't match :) | |
394 | fastcgi_param PATH_INFO $fastcgi_script_name; | |
395 | fastcgi_param SCRIPT_NAME ""; | |
4e893b6e | 396 | } |
076bf0cf | 397 | } |
4e893b6e | 398 | |
f44bd7dc CAW |
399 | The first four ``location`` directives instruct Nginx to serve the |
400 | static and uploaded files directly rather than through the MediaGoblin | |
401 | process. This approach is faster and requires less memory. | |
402 | ||
403 | .. note:: | |
404 | ||
405 | The user who owns the Nginx process, normally ``www-data``, | |
406 | requires execute permission on the directories ``static``, | |
407 | ``public``, ``theme_static`` and ``plugin_static`` plus all their | |
408 | parent directories. This user also requires read permission on all | |
409 | the files within these directories. This is normally the default. | |
410 | ||
4e893b6e | 411 | Now, nginx instance is configured to serve the MediaGoblin |
412 | application. Perform a quick test to ensure that this configuration | |
413 | works. Restart nginx so it picks up your changes, with a command that | |
076bf0cf | 414 | resembles one of the following (as the root user):: |
4e893b6e | 415 | |
076bf0cf WKG |
416 | sudo /etc/init.d/nginx restart |
417 | sudo /etc/rc.d/nginx restart | |
4e893b6e | 418 | |
419 | Now start MediaGoblin. Use the following command sequence as an | |
076bf0cf | 420 | example:: |
4e893b6e | 421 | |
076bf0cf WKG |
422 | cd /srv/mediagoblin.example.org/mediagoblin/ |
423 | ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 | |
4e893b6e | 424 | |
425 | Visit the site you've set up in your browser by visiting | |
518c5eb3 | 426 | <http://mediagoblin.example.org>. You should see MediaGoblin! |
4e893b6e | 427 | |
4e893b6e | 428 | .. note:: |
429 | ||
a085dda5 | 430 | The configuration described above is sufficient for development and |
431 | smaller deployments. However, for larger production deployments | |
432 | with larger processing requirements, see the | |
433 | ":doc:`production-deployments`" documentation. | |
a7d2a892 ST |
434 | |
435 | ||
436 | Apache | |
437 | ~~~~~~ | |
438 | ||
041d2fd7 CAW |
439 | Instructions and scripts for running MediaGoblin on an Apache server |
440 | can be found on the `MediaGoblin wiki <http://wiki.mediagoblin.org/Deployment>`_. | |
b835e153 E |
441 | |
442 | ||
443 | Security Considerations | |
444 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
445 | ||
446 | .. warning:: | |
447 | ||
448 | The directory ``user_dev/crypto/`` contains some very | |
449 | sensitive files. | |
450 | Especially the ``itsdangeroussecret.bin`` is very important | |
451 | for session security. Make sure not to leak its contents anywhere. | |
452 | If the contents gets leaked nevertheless, delete your file | |
453 | and restart the server, so that it creates a new secret key. | |
fd5c35e5 JC |
454 | All previous sessions will be invalidated. |
455 | ||
f44bd7dc CAW |
456 | .. |
457 | Local variables: | |
458 | fill-column: 70 | |
459 | End: |