Commit | Line | Data |
---|---|---|
4e893b6e | 1 | ===================== |
2 | Deploying MediaGoblin | |
3 | ===================== | |
00fdc7bd | 4 | |
e260065a CAW |
5 | GNU MediaGoblin is fairly new and so at the time of writing, there |
6 | aren't easy package-manager-friendly methods to install MediaGoblin. | |
7 | However, doing a basic install isn't too complex in and of itself. | |
56d507b6 | 8 | |
e260065a CAW |
9 | There's an almost infinite way to deploy things... for now, we'll keep |
10 | it simple with some assumptions and use a setup that combines | |
11 | mediagoblin + virtualenv + fastcgi + nginx on a .deb or .rpm based | |
12 | GNU/Linux distro. | |
13 | ||
14 | Note: these tools are for administrators wanting to deploy a fresh | |
15 | install. If instead you want to join in as a contributor, see our | |
16 | `Hacking HOWTO <http://wiki.mediagoblin.org/HackingHowto>`_ instead. | |
17 | ||
4e893b6e | 18 | Prepare System |
19 | -------------- | |
e260065a | 20 | |
4e893b6e | 21 | Dependencies |
22 | ~~~~~~~~~~~~ | |
e260065a | 23 | |
4e893b6e | 24 | MediaGoblin has the following core dependencies: |
e260065a | 25 | |
4e893b6e | 26 | - Python 2.6 or 2.7 |
27 | - `python-lxml <http://lxml.de/>`_ | |
28 | - `git <http://git-scm.com/>`_ | |
29 | - `MongoDB <http://www.mongodb.org/>`_ | |
30 | - `Python Imaging Library <http://www.pythonware.com/products/pil/>`_ (PIL) | |
31 | - `virtualenv <http://www.virtualenv.org/>`_ | |
e260065a | 32 | |
4e893b6e | 33 | On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and |
34 | derivatives) issue the following command: :: | |
e260065a | 35 | |
4e893b6e | 36 | sudo apt-get install mongodb git-core python python-dev python-lxml python-imaging python-virtualenv |
e260065a | 37 | |
4e893b6e | 38 | On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the |
39 | following command: :: | |
40 | ||
41 | yum install mongodb-server python-paste-deploy python-paste-script git-core python python-devel python-lxml python-imaging python-virtualenv | |
e260065a CAW |
42 | |
43 | Configure MongoDB | |
4e893b6e | 44 | ~~~~~~~~~~~~~~~~~ |
45 | ||
46 | After installing MongoDB some preliminary database configuration may | |
47 | be necessary. | |
48 | ||
49 | Ensure that MongoDB `journaling <http://www.mongodb.org/display/DOCS/Journaling>`_ | |
50 | is enabled. Journaling is enabled by default in version 2.0 and later | |
51 | 64-bit MongoDB instances. Check your deployment, and consider enabling | |
52 | journaling if you're running 32-bit systems or earlier version. | |
e260065a | 53 | |
4e893b6e | 54 | .. warning:: |
e260065a | 55 | |
4e893b6e | 56 | Running MongoDB without journaling risks general data corruption |
57 | and raises the possibility of losing data within a 60-second | |
58 | window when the server restarts. | |
e260065a | 59 | |
4e893b6e | 60 | MediaGoblin recommends enabling MongoDB's journaling feature by |
61 | adding a ``--journal`` flag to the command line or a "``journal: | |
62 | true``" option to the configuration file. | |
e260065a | 63 | |
4e893b6e | 64 | MongoDB can take a lot of space by default. If you're planning on |
65 | running a smaller instance, consider the `scaling down guide | |
66 | <http://wiki.mediagoblin.org/Scaling_Down>`_ for some appropriate | |
67 | tradeoffs to conserve space. | |
17c71230 | 68 | |
4e893b6e | 69 | Drop Privileges for MediaGoblin |
70 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
17c71230 | 71 | |
4e893b6e | 72 | As MediaGoblin does not require special permissions or elevated |
73 | access, you should run MediaGoblin under an existing non-root user or | |
74 | preferably create a dedicated user for the purpose of running | |
75 | MediaGoblin. Consult your distribution's documentation on how to | |
76 | create "system account" or dedicated service user. Ensure that it is | |
77 | not possible to log in to your system with as this user. | |
17c71230 | 78 | |
4e893b6e | 79 | You should create a working directory for MediaGoblin. This document |
80 | assumes your local git repository will be located at ``/srv/mediagoblin.example.org/mediagoblin/`` | |
81 | for this documentation. Substitute your prefer ed local deployment path | |
82 | as needed. | |
17c71230 | 83 | |
4e893b6e | 84 | This document assumes that all operations are performed as this |
85 | user. To drop privileges to this user, run the following command: :: | |
17c71230 CAW |
86 | |
87 | ||
4e893b6e | 88 | su - [mediagoblin]`` |
89 | ||
90 | Where, "``[mediagoblin]`` is the username of the system user that will | |
91 | run MediaGoblin. | |
92 | ||
e260065a | 93 | Install MediaGoblin and Virtualenv |
4e893b6e | 94 | ---------------------------------- |
e260065a | 95 | |
4e893b6e | 96 | As of |version|, MediaGoblin has a rapid development pace. As a result |
97 | the following instructions recommend installing from the ``master`` | |
98 | branch of the git repository. Eventually production deployments will | |
99 | want to transition to running from more consistent releases. | |
e260065a | 100 | |
4e893b6e | 101 | Issue the following commands, to create and change the working |
102 | directory. Modify these commands to reflect your own environment: :: | |
17c71230 | 103 | |
4e893b6e | 104 | mkdir -p /srv/mediagoblin.example.org/ |
105 | cd /srv/mediagoblin.example.org/ | |
17c71230 | 106 | |
4e893b6e | 107 | Clone the MediaGoblin repository: :: |
e260065a | 108 | |
4e893b6e | 109 | git clone git://gitorious.org/mediagoblin/mediagoblin.git |
e260065a | 110 | |
4e893b6e | 111 | And setup the in-package virtualenv: :: |
e260065a | 112 | |
4e893b6e | 113 | cd mediagoblin |
114 | virtualenv . && ./bin/python setup.py develop | |
e260065a | 115 | |
4e893b6e | 116 | .. note:: |
e260065a | 117 | |
4e893b6e | 118 | If you have problems here, consider trying to install virtualenv |
119 | with the ``--distribute`` or ``--no-site-packages`` options. If | |
120 | your system's default Python is in the 3.x series you man need to | |
121 | run ``virtualenv`` with the ``--python=python2.7`` or | |
122 | ``--python=python2.6`` options. | |
e260065a | 123 | |
4e893b6e | 124 | The above provides an in-package install of ``virtualenv``. While this |
125 | is counter to the conventional ``virtualenv`` configuration, it is | |
126 | more reliable and considerably easier to configure and illustrate. If | |
127 | you're familiar with Python packaging you may consider deploying with | |
128 | your preferred the method. | |
e260065a | 129 | |
99192f24 CAW |
130 | Assuming you are going to deploy with fastcgi, you should also install |
131 | flup: :: | |
132 | ||
133 | ./bin/easy_install flup | |
134 | ||
4e893b6e | 135 | This concludes the initial configuration of the development |
136 | environment. In the future, if at any point you want update your | |
137 | codebase, you should also run: :: | |
e260065a | 138 | |
4e893b6e | 139 | ./bin/python setup.py develop --upgrade && ./bin/gmg migrate. |
e260065a | 140 | |
4e893b6e | 141 | Deploy MediaGoblin Services |
142 | --------------------------- | |
e260065a | 143 | |
4e893b6e | 144 | Test the Server |
145 | ~~~~~~~~~~~~~~~ | |
e260065a | 146 | |
4e893b6e | 147 | At this point MediaGoblin should be properly installed. You can |
148 | test the deployment with the following command: :: | |
e260065a | 149 | |
4e893b6e | 150 | ./lazyserver.sh --server-name=broadcast |
e260065a | 151 | |
4e893b6e | 152 | You should be able to connect to the machine on port 6543 in your |
153 | browser to confirm that the service is operable. | |
e260065a | 154 | |
4e893b6e | 155 | Connect the Webserver to MediaGoblin with FastCGI |
156 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
56d507b6 | 157 | |
94011579 | 158 | This section describes how to configure MediaGoblin to work via |
4e893b6e | 159 | fastcgi. Our configuration example will use nginx, however, you may |
160 | use any webserver of your choice as long as it supports the FastCGI | |
161 | protocol. If you do not already have a web server, consider nginx, as | |
162 | the configuration files may be more clear than the | |
163 | alternatives. | |
164 | ||
165 | Create a configuration file at | |
166 | ``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link | |
167 | into a directory that will be included in your ``nginx`` configuration | |
168 | (e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with | |
169 | one of the following commands (as the root user:) :: | |
170 | ||
171 | ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/ | |
172 | ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/ | |
173 | ||
174 | Modify these commands and locations depending on your preferences and | |
175 | the existing configuration of your nginx instance. The contents of | |
176 | this ``nginx.conf`` file should be modeled on the following: :: | |
177 | ||
178 | server { | |
179 | ################################################# | |
180 | # Stock useful config options, but ignore them :) | |
181 | ################################################# | |
182 | include /etc/nginx/mime.types; | |
183 | ||
184 | autoindex off; | |
185 | default_type application/octet-stream; | |
186 | sendfile on; | |
187 | ||
188 | # Gzip | |
189 | gzip on; | |
190 | gzip_min_length 1024; | |
191 | gzip_buffers 4 32k; | |
192 | gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css; | |
193 | ||
194 | ##################################### | |
195 | # Mounting MediaGoblin stuff | |
196 | # This is the section you should read | |
197 | ##################################### | |
198 | ||
199 | server_name mediagoblin.example.org www.mediagoblin.example.org; | |
200 | access_log /var/log/nginx/mediagoblin.example.access.log; | |
201 | error_log /var/log/nginx/mediagoblin.example.error.log; | |
202 | ||
203 | # MediaGoblin's stock static files: CSS, JS, etc. | |
204 | location /mgoblin_static/ { | |
205 | alias /srv/mediagoblin.example.org/mediagoblin/static/; | |
206 | } | |
207 | ||
208 | # Instance specific media: | |
209 | location /mgoblin_media/ { | |
210 | alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/; | |
211 | } | |
212 | ||
213 | # Mounting MediaGoblin itself via fastcgi. | |
214 | location / { | |
215 | fastcgi_pass 127.0.0.1:26543; | |
216 | include /etc/nginx/fastcgi_params; | |
02e99c78 CAW |
217 | |
218 | # our understanding vs nginx's handling of script_name vs | |
219 | # path_info don't match :) | |
220 | fastcgi_param PATH_INFO $fastcgi_script_name; | |
221 | fastcgi_param SCRIPT_NAME ""; | |
4e893b6e | 222 | } |
223 | } | |
224 | ||
225 | Now, nginx instance is configured to serve the MediaGoblin | |
226 | application. Perform a quick test to ensure that this configuration | |
227 | works. Restart nginx so it picks up your changes, with a command that | |
228 | resembles one of the following (as the root user:) :: | |
229 | ||
230 | sudo /etc/init.d/nginx restart | |
231 | sudo /etc/rc.d/nginx restart | |
232 | ||
233 | Now start MediaGoblin. Use the following command sequence as an | |
234 | example: :: | |
235 | ||
236 | cd /srv/mediagoblin.example.org/mediagoblin/ | |
237 | ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 | |
238 | ||
239 | Visit the site you've set up in your browser by visiting | |
240 | <http://mediagobilin.example.org>. You should see MediaGoblin! | |
241 | ||
242 | Production MediaGoblin Deployments with Paste | |
243 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
244 | ||
245 | The instance configured with ``lazyserver`` is not ideal for a | |
246 | production MediaGoblin deployment. Ideally, you should be able to use | |
247 | a a control script (i.e. init script.) to launch and restart the | |
248 | MediaGoblin process. | |
249 | ||
250 | Use the following command as the basis for such a script: :: | |
251 | ||
252 | CELERY_ALWAYS_EAGER=true \ | |
253 | /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ | |
254 | /srv/mediagoblin.example.org/mediagoblin/paste.ini \ | |
255 | --pid-file=/tmp/mediagoblin.pid \ | |
256 | --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 \ | |
257 | ||
258 | .. note:: | |
259 | ||
260 | The above configuration places MediaGoblin in "always eager" mode | |
261 | with Celery. This is fine for development and smaller | |
262 | deployments. However, if you're getting into the really large | |
263 | deployment category, consider reading the section of this manual on | |
264 | Celery. |