Commit | Line | Data |
---|---|---|
473a4431 CAW |
1 | .. MediaGoblin Documentation |
2 | ||
3 | Written in 2011, 2012 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 | ||
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 | |
4e893b6e | 35 | Prepare System |
36 | -------------- | |
e260065a | 37 | |
4e893b6e | 38 | Dependencies |
39 | ~~~~~~~~~~~~ | |
e260065a | 40 | |
4e893b6e | 41 | MediaGoblin has the following core dependencies: |
e260065a | 42 | |
4e893b6e | 43 | - Python 2.6 or 2.7 |
44 | - `python-lxml <http://lxml.de/>`_ | |
45 | - `git <http://git-scm.com/>`_ | |
775ec9e8 | 46 | - `SQLite <http://www.sqlite.org/>`_/`PostgreSQL <http://www.postgresql.org/>`_ |
4e893b6e | 47 | - `Python Imaging Library <http://www.pythonware.com/products/pil/>`_ (PIL) |
48 | - `virtualenv <http://www.virtualenv.org/>`_ | |
e260065a | 49 | |
4e893b6e | 50 | On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and |
7798f911 | 51 | derivatives) issue the following command:: |
e260065a | 52 | |
775ec9e8 | 53 | sudo apt-get install git-core python python-dev python-lxml \ |
076bf0cf | 54 | python-imaging python-virtualenv |
e260065a | 55 | |
4e893b6e | 56 | On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the |
7798f911 | 57 | following command:: |
4e893b6e | 58 | |
775ec9e8 | 59 | yum install python-paste-deploy python-paste-script \ |
076bf0cf WKG |
60 | git-core python python-devel python-lxml python-imaging \ |
61 | python-virtualenv | |
e260065a | 62 | |
775ec9e8 JW |
63 | Configure PostgreSQL |
64 | ~~~~~~~~~~~~~~~~~~~~ | |
65 | ||
66 | .. note:: | |
67 | ||
7798f911 WKG |
68 | MediaGoblin currently supports PostgreSQL and SQLite. The default is a |
69 | local SQLite database. This will "just work" for small deployments. | |
775ec9e8 | 70 | |
7798f911 WKG |
71 | For medium to large deployments we recommend PostgreSQL. |
72 | ||
73 | If you don't want/need postgres, skip this section. | |
74 | ||
75 | These are the packages needed for Debian Wheezy (testing):: | |
775ec9e8 | 76 | |
21a84362 | 77 | sudo apt-get install postgresql postgresql-client python-psycopg2 |
775ec9e8 JW |
78 | |
79 | The installation process will create a new *system* user named ``postgres``, | |
80 | it will have privilegies sufficient to manage the database. We will create a | |
81 | new database user with restricted privilegies and a new database owned by our | |
82 | restricted database user for our MediaGoblin instance. | |
83 | ||
84 | In this example, the database user will be ``mediagoblin`` and the database | |
85 | name will be ``mediagoblin`` too. | |
86 | ||
7798f911 | 87 | To create our new user, run:: |
775ec9e8 JW |
88 | |
89 | sudo -u postgres createuser mediagoblin | |
90 | ||
7798f911 | 91 | then answer NO to *all* the questions:: |
775ec9e8 JW |
92 | |
93 | Shall the new role be a superuser? (y/n) n | |
94 | Shall the new role be allowed to create databases? (y/n) n | |
95 | Shall the new role be allowed to create more new roles? (y/n) n | |
96 | ||
7798f911 | 97 | then create the database all our MediaGoblin data should be stored in:: |
775ec9e8 JW |
98 | |
99 | sudo -u postgres createdb -E UNICODE -O mediagoblin mediagoblin | |
100 | ||
101 | where the first ``mediagoblin`` is the database owner and the second | |
102 | ``mediagoblin`` is the database name. | |
103 | ||
104 | .. caution:: Where is the password? | |
105 | ||
106 | These steps enable you to authenticate to the database in a password-less | |
107 | manner via local UNIX authentication provided you run the MediaGoblin | |
108 | application as a user with the same name as the user you created in | |
109 | PostgreSQL. | |
110 | ||
111 | More on this in :ref:`Drop Privileges for MediaGoblin <drop-privileges-for-mediagoblin>`. | |
112 | ||
113 | ||
775ec9e8 JW |
114 | .. _drop-privileges-for-mediagoblin: |
115 | ||
4e893b6e | 116 | Drop Privileges for MediaGoblin |
117 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
17c71230 | 118 | |
4e893b6e | 119 | As MediaGoblin does not require special permissions or elevated |
120 | access, you should run MediaGoblin under an existing non-root user or | |
121 | preferably create a dedicated user for the purpose of running | |
122 | MediaGoblin. Consult your distribution's documentation on how to | |
123 | create "system account" or dedicated service user. Ensure that it is | |
124 | not possible to log in to your system with as this user. | |
17c71230 | 125 | |
4e893b6e | 126 | You should create a working directory for MediaGoblin. This document |
076bf0cf WKG |
127 | assumes your local git repository will be located at |
128 | ``/srv/mediagoblin.example.org/mediagoblin/`` for this documentation. | |
129 | Substitute your prefer ed local deployment path as needed. | |
17c71230 | 130 | |
4e893b6e | 131 | This document assumes that all operations are performed as this |
7798f911 | 132 | user. To drop privileges to this user, run the following command:: |
17c71230 | 133 | |
076bf0cf | 134 | su - [mediagoblin] |
17c71230 | 135 | |
076bf0cf | 136 | Where, "``[mediagoblin]``" is the username of the system user that will |
4e893b6e | 137 | run MediaGoblin. |
138 | ||
e260065a | 139 | Install MediaGoblin and Virtualenv |
4e893b6e | 140 | ---------------------------------- |
e260065a | 141 | |
076bf0cf WKG |
142 | .. note:: |
143 | ||
7798f911 | 144 | MediaGoblin is still developing rapidly. As a result |
076bf0cf WKG |
145 | the following instructions recommend installing from the ``master`` |
146 | branch of the git repository. Eventually production deployments will | |
147 | want to transition to running from more consistent releases. | |
e260065a | 148 | |
4e893b6e | 149 | Issue the following commands, to create and change the working |
076bf0cf | 150 | directory. Modify these commands to reflect your own environment:: |
17c71230 | 151 | |
076bf0cf WKG |
152 | mkdir -p /srv/mediagoblin.example.org/ |
153 | cd /srv/mediagoblin.example.org/ | |
17c71230 | 154 | |
076bf0cf | 155 | Clone the MediaGoblin repository:: |
e260065a | 156 | |
076bf0cf | 157 | git clone git://gitorious.org/mediagoblin/mediagoblin.git |
e260065a | 158 | |
7798f911 | 159 | And set up the in-package virtualenv:: |
e260065a | 160 | |
076bf0cf | 161 | cd mediagoblin |
95ff15d6 | 162 | (virtualenv --system-site-packages . || virtualenv .) && ./bin/python setup.py develop |
e260065a | 163 | |
4e893b6e | 164 | .. note:: |
e260065a | 165 | |
4e893b6e | 166 | If you have problems here, consider trying to install virtualenv |
167 | with the ``--distribute`` or ``--no-site-packages`` options. If | |
168 | your system's default Python is in the 3.x series you man need to | |
169 | run ``virtualenv`` with the ``--python=python2.7`` or | |
170 | ``--python=python2.6`` options. | |
e260065a | 171 | |
4e893b6e | 172 | The above provides an in-package install of ``virtualenv``. While this |
173 | is counter to the conventional ``virtualenv`` configuration, it is | |
174 | more reliable and considerably easier to configure and illustrate. If | |
175 | you're familiar with Python packaging you may consider deploying with | |
176 | your preferred the method. | |
e260065a | 177 | |
076bf0cf WKG |
178 | Assuming you are going to deploy with FastCGI, you should also install |
179 | flup:: | |
99192f24 | 180 | |
076bf0cf | 181 | ./bin/easy_install flup |
99192f24 | 182 | |
4e893b6e | 183 | This concludes the initial configuration of the development |
8d9aa03f | 184 | environment. In the future, when you update your |
076bf0cf | 185 | codebase, you should also run:: |
e260065a | 186 | |
084a6190 | 187 | ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate |
e260065a | 188 | |
4e893b6e | 189 | Deploy MediaGoblin Services |
190 | --------------------------- | |
e260065a | 191 | |
775ec9e8 JW |
192 | Configure MediaGoblin to use the PostgreSQL database |
193 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
194 | ||
7798f911 WKG |
195 | If you are using postgres, edit the ``[mediagoblin]`` section in your |
196 | ``mediagoblin_local.ini`` and put in:: | |
775ec9e8 JW |
197 | |
198 | sql_engine = postgresql:///mediagoblin | |
199 | ||
200 | if you are running the MediaGoblin application as the same 'user' as the | |
201 | database owner. | |
202 | ||
7798f911 | 203 | |
775ec9e8 JW |
204 | Update database data structures |
205 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
206 | ||
7798f911 | 207 | Before you start using the database, you need to run:: |
775ec9e8 JW |
208 | |
209 | ./bin/gmg dbupdate | |
210 | ||
211 | to populate the database with the MediaGoblin data structures. | |
212 | ||
213 | ||
4e893b6e | 214 | Test the Server |
215 | ~~~~~~~~~~~~~~~ | |
e260065a | 216 | |
4e893b6e | 217 | At this point MediaGoblin should be properly installed. You can |
076bf0cf | 218 | test the deployment with the following command:: |
e260065a | 219 | |
076bf0cf | 220 | ./lazyserver.sh --server-name=broadcast |
e260065a | 221 | |
4e893b6e | 222 | You should be able to connect to the machine on port 6543 in your |
223 | browser to confirm that the service is operable. | |
e260065a | 224 | |
cd1abb11 CAW |
225 | .. _webserver-config: |
226 | ||
4e893b6e | 227 | Connect the Webserver to MediaGoblin with FastCGI |
228 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
56d507b6 | 229 | |
94011579 | 230 | This section describes how to configure MediaGoblin to work via |
076bf0cf | 231 | FastCGI. Our configuration example will use nginx, however, you may |
4e893b6e | 232 | use any webserver of your choice as long as it supports the FastCGI |
233 | protocol. If you do not already have a web server, consider nginx, as | |
234 | the configuration files may be more clear than the | |
235 | alternatives. | |
236 | ||
237 | Create a configuration file at | |
238 | ``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link | |
239 | into a directory that will be included in your ``nginx`` configuration | |
240 | (e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with | |
076bf0cf | 241 | one of the following commands (as the root user):: |
4e893b6e | 242 | |
076bf0cf WKG |
243 | ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/ |
244 | ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/ | |
4e893b6e | 245 | |
246 | Modify these commands and locations depending on your preferences and | |
247 | the existing configuration of your nginx instance. The contents of | |
076bf0cf WKG |
248 | this ``nginx.conf`` file should be modeled on the following:: |
249 | ||
250 | server { | |
251 | ################################################# | |
252 | # Stock useful config options, but ignore them :) | |
253 | ################################################# | |
254 | include /etc/nginx/mime.types; | |
255 | ||
256 | autoindex off; | |
257 | default_type application/octet-stream; | |
258 | sendfile on; | |
259 | ||
260 | # Gzip | |
261 | gzip on; | |
262 | gzip_min_length 1024; | |
263 | gzip_buffers 4 32k; | |
264 | gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css; | |
265 | ||
266 | ##################################### | |
267 | # Mounting MediaGoblin stuff | |
268 | # This is the section you should read | |
269 | ##################################### | |
270 | ||
271 | # Change this to update the upload size limit for your users | |
272 | client_max_body_size 8m; | |
273 | ||
274 | server_name mediagoblin.example.org www.mediagoblin.example.org; | |
275 | access_log /var/log/nginx/mediagoblin.example.access.log; | |
276 | error_log /var/log/nginx/mediagoblin.example.error.log; | |
277 | ||
278 | # MediaGoblin's stock static files: CSS, JS, etc. | |
279 | location /mgoblin_static/ { | |
280 | alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/; | |
281 | } | |
282 | ||
283 | # Instance specific media: | |
284 | location /mgoblin_media/ { | |
285 | alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/; | |
286 | } | |
287 | ||
8d051cc0 CAW |
288 | # Theme static files (usually symlinked in) |
289 | location /theme_static/ { | |
290 | alias /srv/mediagoblin.example.org/mediagoblin/user_dev/theme_static/; | |
291 | } | |
292 | ||
076bf0cf WKG |
293 | # Mounting MediaGoblin itself via FastCGI. |
294 | location / { | |
295 | fastcgi_pass 127.0.0.1:26543; | |
296 | include /etc/nginx/fastcgi_params; | |
297 | ||
298 | # our understanding vs nginx's handling of script_name vs | |
299 | # path_info don't match :) | |
300 | fastcgi_param PATH_INFO $fastcgi_script_name; | |
301 | fastcgi_param SCRIPT_NAME ""; | |
4e893b6e | 302 | } |
076bf0cf | 303 | } |
4e893b6e | 304 | |
305 | Now, nginx instance is configured to serve the MediaGoblin | |
306 | application. Perform a quick test to ensure that this configuration | |
307 | works. Restart nginx so it picks up your changes, with a command that | |
076bf0cf | 308 | resembles one of the following (as the root user):: |
4e893b6e | 309 | |
076bf0cf WKG |
310 | sudo /etc/init.d/nginx restart |
311 | sudo /etc/rc.d/nginx restart | |
4e893b6e | 312 | |
313 | Now start MediaGoblin. Use the following command sequence as an | |
076bf0cf | 314 | example:: |
4e893b6e | 315 | |
076bf0cf WKG |
316 | cd /srv/mediagoblin.example.org/mediagoblin/ |
317 | ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 | |
4e893b6e | 318 | |
319 | Visit the site you've set up in your browser by visiting | |
518c5eb3 | 320 | <http://mediagoblin.example.org>. You should see MediaGoblin! |
4e893b6e | 321 | |
4e893b6e | 322 | .. note:: |
323 | ||
a085dda5 | 324 | The configuration described above is sufficient for development and |
325 | smaller deployments. However, for larger production deployments | |
326 | with larger processing requirements, see the | |
327 | ":doc:`production-deployments`" documentation. |