diff options
Diffstat (limited to 'docs/source')
| -rw-r--r-- | docs/source/conf.py | 4 | ||||
| -rw-r--r-- | docs/source/configuration.rst | 105 | ||||
| -rw-r--r-- | docs/source/deploying.rst | 270 | ||||
| -rw-r--r-- | docs/source/index.rst | 1 |
4 files changed, 367 insertions, 13 deletions
diff --git a/docs/source/conf.py b/docs/source/conf.py index 7ea3a340..eee9900f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -48,9 +48,9 @@ copyright = u'2011, Free Software Foundation, Inc and contributors' # built documents. # # The short X.Y version. -version = '0.0.5' +version = '0.1.0' # The full version, including alpha/beta/rc tags. -release = '0.0.5' +release = '0.1.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst new file mode 100644 index 00000000..093f492c --- /dev/null +++ b/docs/source/configuration.rst @@ -0,0 +1,105 @@ +.. _configuration-chapter: + +======================== +Configuring MediaGoblin +======================== + +So! You've got MediaGoblin up and running, but you need to adjust +some configuration parameters. Well you've come to the right place! + +MediaGoblin's config files +========================== + +When configuring MediaGoblin, there are two files you might want to +make local modified versions of, and one extra file that might be +helpful to look at. Let's examine these. + +mediagoblin.ini + This is the config file for MediaGoblin, the application. If you want to + tweak settings for MediaGoblin, you'll usually tweak them here. + +paste.ini + This is primarily a server configuration file, on the python side + (specifically, on the wsgi side, via `paste deploy + <http://pythonpaste.org/deploy/>`_ / `paste script + <http://pythonpaste.org/script/>`_). It also sets up some + middleware that you can mostly ignore, except to configure + sessions... more on that later. If you are adding a different + python server other than fastcgi / plain http, you might configure + it here. You probably won't need to change this file very much. + + +There's one more file that you certainly won't change unless you're +making coding contributions to mediagoblin, but which can be useful to +read and reference: + +mediagoblin/config_spec.ini + This file is actually a specification for mediagoblin.ini itself, as + a config file! It defines types and defaults. Sometimes it's a + good place to look for documentation... or to find that hidden + option that we didn't tell you about. :) + + +Making local copies +=================== + +Let's assume you're doing the virtualenv setup described elsewhere in this +manual, and you need to make local tweaks to the config files. How do you do +that? Let's see. + +To make changes to mediagoblin.ini: + + cp mediagoblin.ini mediagoblin_local.ini + +To make changes to paste.ini: + cp paste.ini paste_local.ini + +From here you should be able to make direct adjustments to the files, +and most of the commands described elsewhere in this manual will "notice" +your local config files and use those instead of the non-local version. + +(Note that all commands provide a way to pass in a specific config +file also, usually by a -cf flag.) + +Common changes +============== + +Enabling email notifications +---------------------------- + +You'll almost certainly want to enable sending emails. By default, +MediaGoblin doesn't really do this... for the sake of developer +convenience, it runs in "email debug mode". Change this: + + email_debug_mode = false + +You can (and should) change the "from" email address by setting +``email_sender_address``. + +Note that you need a mailer daemon running for this to work. + +If you have more custom SMTP settings, you also have the following +options at your disposal, which are all optional, and do exactly what +they sound like. + + - email_smtp_host + - email_smtp_port + - email_smtp_user + - email_smtp_pass + +All other configuration changes +------------------------------- + +To be perfectly honest, there are quite a few options and I'm not +going to be able to get to documanting them all in time for 0.1.0. + +So here's a cop-out section saying that if you get into trouble, hop +onto IRC and we'll help you out: + + #mediagoblin on irc.freenode.net + +Celery +====== + +We should point to another celery-specific section of the document +actually :) diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index db92257a..b944a3d3 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -1,16 +1,264 @@ -.. _deployment-chapter: +===================== +Deploying MediaGoblin +===================== -======================= - Deploying MediaGoblin -======================= +GNU MediaGoblin is fairly new and so at the time of writing, there +aren't easy package-manager-friendly methods to install MediaGoblin. +However, doing a basic install isn't too complex in and of itself. -Step 1: Write code that can be deployed. +There's an almost infinite way to deploy things... for now, we'll keep +it simple with some assumptions and use a setup that combines +mediagoblin + virtualenv + fastcgi + nginx on a .deb or .rpm based +GNU/Linux distro. -Step 2: ? +Note: these tools are for administrators wanting to deploy a fresh +install. If instead you want to join in as a contributor, see our +`Hacking HOWTO <http://wiki.mediagoblin.org/HackingHowto>`_ instead. -Step 3: Write the deployment guide and profit! +Prepare System +-------------- -But seriously, this is a stub since we're not quite there (yet) but if -you want to see where we are now, you can try to run the latest -development version by following the instructions on -`the wiki <http://wiki.mediagoblin.org/>`_. +Dependencies +~~~~~~~~~~~~ + +MediaGoblin has the following core dependencies: + +- Python 2.6 or 2.7 +- `python-lxml <http://lxml.de/>`_ +- `git <http://git-scm.com/>`_ +- `MongoDB <http://www.mongodb.org/>`_ +- `Python Imaging Library <http://www.pythonware.com/products/pil/>`_ (PIL) +- `virtualenv <http://www.virtualenv.org/>`_ + +On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and +derivatives) issue the following command: :: + + sudo apt-get install mongodb git-core python python-dev python-lxml python-imaging python-virtualenv + +On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the +following command: :: + + yum install mongodb-server python-paste-deploy python-paste-script git-core python python-devel python-lxml python-imaging python-virtualenv + +Configure MongoDB +~~~~~~~~~~~~~~~~~ + +After installing MongoDB some preliminary database configuration may +be necessary. + +Ensure that MongoDB `journaling <http://www.mongodb.org/display/DOCS/Journaling>`_ +is enabled. Journaling is enabled by default in version 2.0 and later +64-bit MongoDB instances. Check your deployment, and consider enabling +journaling if you're running 32-bit systems or earlier version. + +.. warning:: + + Running MongoDB without journaling risks general data corruption + and raises the possibility of losing data within a 60-second + window when the server restarts. + + MediaGoblin recommends enabling MongoDB's journaling feature by + adding a ``--journal`` flag to the command line or a "``journal: + true``" option to the configuration file. + +MongoDB can take a lot of space by default. If you're planning on +running a smaller instance, consider the `scaling down guide +<http://wiki.mediagoblin.org/Scaling_Down>`_ for some appropriate +tradeoffs to conserve space. + +Drop Privileges for MediaGoblin +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As MediaGoblin does not require special permissions or elevated +access, you should run MediaGoblin under an existing non-root user or +preferably create a dedicated user for the purpose of running +MediaGoblin. Consult your distribution's documentation on how to +create "system account" or dedicated service user. Ensure that it is +not possible to log in to your system with as this user. + +You should create a working directory for MediaGoblin. This document +assumes your local git repository will be located at ``/srv/mediagoblin.example.org/mediagoblin/`` +for this documentation. Substitute your prefer ed local deployment path +as needed. + +This document assumes that all operations are performed as this +user. To drop privileges to this user, run the following command: :: + + + su - [mediagoblin]`` + +Where, "``[mediagoblin]`` is the username of the system user that will +run MediaGoblin. + +Install MediaGoblin and Virtualenv +---------------------------------- + +As of |version|, MediaGoblin has a rapid development pace. As a result +the following instructions recommend installing from the ``master`` +branch of the git repository. Eventually production deployments will +want to transition to running from more consistent releases. + +Issue the following commands, to create and change the working +directory. Modify these commands to reflect your own environment: :: + + mkdir -p /srv/mediagoblin.example.org/ + cd /srv/mediagoblin.example.org/ + +Clone the MediaGoblin repository: :: + + git clone git://gitorious.org/mediagoblin/mediagoblin.git + +And setup the in-package virtualenv: :: + + cd mediagoblin + virtualenv . && ./bin/python setup.py develop + +.. note:: + + If you have problems here, consider trying to install virtualenv + with the ``--distribute`` or ``--no-site-packages`` options. If + your system's default Python is in the 3.x series you man need to + run ``virtualenv`` with the ``--python=python2.7`` or + ``--python=python2.6`` options. + +The above provides an in-package install of ``virtualenv``. While this +is counter to the conventional ``virtualenv`` configuration, it is +more reliable and considerably easier to configure and illustrate. If +you're familiar with Python packaging you may consider deploying with +your preferred the method. + +Assuming you are going to deploy with fastcgi, you should also install +flup: :: + + ./bin/easy_install flup + +This concludes the initial configuration of the development +environment. In the future, if at any point you want update your +codebase, you should also run: :: + + ./bin/python setup.py develop --upgrade && ./bin/gmg migrate. + +Deploy MediaGoblin Services +--------------------------- + +Test the Server +~~~~~~~~~~~~~~~ + +At this point MediaGoblin should be properly installed. You can +test the deployment with the following command: :: + + ./lazyserver.sh --server-name=broadcast + +You should be able to connect to the machine on port 6543 in your +browser to confirm that the service is operable. + +Connect the Webserver to MediaGoblin with FastCGI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to configure MediaGoblin to work via +fastcgi. Our configuration example will use nginx, however, you may +use any webserver of your choice as long as it supports the FastCGI +protocol. If you do not already have a web server, consider nginx, as +the configuration files may be more clear than the +alternatives. + +Create a configuration file at +``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link +into a directory that will be included in your ``nginx`` configuration +(e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with +one of the following commands (as the root user:) :: + + ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/ + ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/ + +Modify these commands and locations depending on your preferences and +the existing configuration of your nginx instance. The contents of +this ``nginx.conf`` file should be modeled on the following: :: + + server { + ################################################# + # Stock useful config options, but ignore them :) + ################################################# + include /etc/nginx/mime.types; + + autoindex off; + default_type application/octet-stream; + sendfile on; + + # Gzip + gzip on; + gzip_min_length 1024; + gzip_buffers 4 32k; + gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css; + + ##################################### + # Mounting MediaGoblin stuff + # This is the section you should read + ##################################### + + server_name mediagoblin.example.org www.mediagoblin.example.org; + access_log /var/log/nginx/mediagoblin.example.access.log; + error_log /var/log/nginx/mediagoblin.example.error.log; + + # MediaGoblin's stock static files: CSS, JS, etc. + location /mgoblin_static/ { + alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/; + } + + # Instance specific media: + location /mgoblin_media/ { + alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/; + } + + # Mounting MediaGoblin itself via fastcgi. + location / { + fastcgi_pass 127.0.0.1:26543; + include /etc/nginx/fastcgi_params; + + # our understanding vs nginx's handling of script_name vs + # path_info don't match :) + fastcgi_param PATH_INFO $fastcgi_script_name; + fastcgi_param SCRIPT_NAME ""; + } + } + +Now, nginx instance is configured to serve the MediaGoblin +application. Perform a quick test to ensure that this configuration +works. Restart nginx so it picks up your changes, with a command that +resembles one of the following (as the root user:) :: + + sudo /etc/init.d/nginx restart + sudo /etc/rc.d/nginx restart + +Now start MediaGoblin. Use the following command sequence as an +example: :: + + cd /srv/mediagoblin.example.org/mediagoblin/ + ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 + +Visit the site you've set up in your browser by visiting +<http://mediagobilin.example.org>. You should see MediaGoblin! + +Production MediaGoblin Deployments with Paste +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The instance configured with ``lazyserver`` is not ideal for a +production MediaGoblin deployment. Ideally, you should be able to use +a a control script (i.e. init script.) to launch and restart the +MediaGoblin process. + +Use the following command as the basis for such a script: :: + + CELERY_ALWAYS_EAGER=true \ + /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ + /srv/mediagoblin.example.org/mediagoblin/paste.ini \ + --pid-file=/tmp/mediagoblin.pid \ + --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 \ + +.. note:: + + The above configuration places MediaGoblin in "always eager" mode + with Celery. This is fine for development and smaller + deployments. However, if you're getting into the really large + deployment category, consider reading the section of this manual on + Celery. diff --git a/docs/source/index.rst b/docs/source/index.rst index 088b5359..e9f3993e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -14,6 +14,7 @@ Table of Contents: foreword about deploying + configuration help theming codebase |