diff options
Diffstat (limited to 'docs/source/deploying.rst')
| -rw-r--r-- | docs/source/deploying.rst | 211 |
1 files changed, 107 insertions, 104 deletions
diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index 5f07a1d2..4aded2e6 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -11,9 +11,11 @@ it simple with some assumptions and use a setup that combines mediagoblin + virtualenv + fastcgi + nginx on a .deb or .rpm based GNU/Linux distro. -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. +.. note:: + + These tools are for site 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. Prepare System -------------- @@ -33,12 +35,15 @@ MediaGoblin has the following core dependencies: 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 + 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 + yum install mongodb-server python-paste-deploy python-paste-script \ + git-core python python-devel python-lxml python-imaging \ + python-virtualenv Configure MongoDB ~~~~~~~~~~~~~~~~~ @@ -46,10 +51,11 @@ 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. +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:: @@ -77,41 +83,42 @@ 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. +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] - su - [mediagoblin]`` - -Where, "``[mediagoblin]`` is the username of the system user that will +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. +.. note:: + + 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: :: +directory. Modify these commands to reflect your own environment:: - mkdir -p /srv/mediagoblin.example.org/ - cd /srv/mediagoblin.example.org/ + mkdir -p /srv/mediagoblin.example.org/ + cd /srv/mediagoblin.example.org/ -Clone the MediaGoblin repository: :: +Clone the MediaGoblin repository:: - git clone git://gitorious.org/mediagoblin/mediagoblin.git + git clone git://gitorious.org/mediagoblin/mediagoblin.git -And setup the in-package virtualenv: :: +And setup the in-package virtualenv:: - cd mediagoblin - virtualenv . && ./bin/python setup.py develop + cd mediagoblin + virtualenv . && ./bin/python setup.py develop .. note:: @@ -127,11 +134,16 @@ 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: :: +codebase, you should also run:: - ./bin/python setup.py develop --upgrade && ./bin/gmg migrate. + ./bin/python setup.py develop --upgrade && ./bin/gmg migrate. Deploy MediaGoblin Services --------------------------- @@ -140,9 +152,9 @@ Test the Server ~~~~~~~~~~~~~~~ At this point MediaGoblin should be properly installed. You can -test the deployment with the following command: :: +test the deployment with the following command:: - ./lazyserver.sh --server-name=broadcast + ./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. @@ -151,7 +163,7 @@ 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 +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 @@ -161,94 +173,85 @@ 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:) :: +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/ + 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/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; - } +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 + ##################################### + + # Change this to update the upload size limit for your users + client_max_body_size 8m; + + 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:) :: +resembles one of the following (as the root user):: - sudo /etc/init.d/nginx restart - sudo /etc/rc.d/nginx restart + sudo /etc/init.d/nginx restart + sudo /etc/rc.d/nginx restart Now start MediaGoblin. Use the following command sequence as an -example: :: +example:: - cd /srv/mediagoblin.example.org/mediagoblin/ - ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 + 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. + The configuration described above is sufficient for development and + smaller deployments. However, for larger production deployments + with larger processing requirements, see the + ":doc:`production-deployments`" documentation. |