heckyel/mediagoblin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc updates

Browse Source 
* fixed some language
* fixed some consistency issues
* fixed some 80-line-width issues
* fixed some typos and markup problems
This commit is contained in:
Will Kahn-Greene 2011-12-12 10:20:05 -05:00
parent 78dc055e22
commit 076bf0cf28
4 changed files with 135 additions and 125 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
docs/source/configuration.rst
View File

@ -19,13 +19,13 @@ mediagoblin.ini
tweak settings for MediaGoblin, you'll usually tweak them here. tweak settings for MediaGoblin, you'll usually tweak them here.
paste.ini paste.ini
This is primarily a server configuration file, on the python side This is primarily a server configuration file, on the Python side
(specifically, on the wsgi side, via `paste deploy (specifically, on the WSGI side, via `paste deploy
<http://pythonpaste.org/deploy/>`_ / `paste script <http://pythonpaste.org/deploy/>`_ / `paste script
<http://pythonpaste.org/script/>`_). It also sets up some <http://pythonpaste.org/script/>`_). It also sets up some
middleware that you can mostly ignore, except to configure middleware that you can mostly ignore, except to configure
sessions... more on that later. If you are adding a different sessions... more on that later. If you are adding a different
python server other than fastcgi / plain http, you might configure Python server other than fastcgi / plain HTTP, you might configure
it here. You probably won't need to change this file very much. it here. You probably won't need to change this file very much.
@ -47,19 +47,23 @@ 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 manual, and you need to make local tweaks to the config files. How do you do
that? Let's see. that? Let's see.
To make changes to mediagoblin.ini: To make changes to mediagoblin.ini ::
cp mediagoblin.ini mediagoblin_local.ini cp mediagoblin.ini mediagoblin_local.ini
To make changes to paste.ini: To make changes to paste.ini ::
cp paste.ini paste_local.ini
cp paste.ini paste_local.ini
From here you should be able to make direct adjustments to the files, 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" 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. 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 .. note::
file also, usually by a -cf flag.)
Note that all commands provide a way to pass in a specific config
file also, usually by a ``-cf`` flag.
Common changes Common changes
============== ==============
@ -69,9 +73,9 @@ Enabling email notifications
You'll almost certainly want to enable sending emails. By default, You'll almost certainly want to enable sending emails. By default,
MediaGoblin doesn't really do this... for the sake of developer MediaGoblin doesn't really do this... for the sake of developer
convenience, it runs in "email debug mode". Change this: convenience, it runs in "email debug mode". Change this::
email_debug_mode = false email_debug_mode = false
You can (and should) change the "from" email address by setting You can (and should) change the "from" email address by setting
``email_sender_address``. ``email_sender_address``.
@ -82,21 +86,21 @@ If you have more custom SMTP settings, you also have the following
options at your disposal, which are all optional, and do exactly what options at your disposal, which are all optional, and do exactly what
they sound like. they sound like.
- email_smtp_host - email_smtp_host
- email_smtp_port - email_smtp_port
- email_smtp_user - email_smtp_user
- email_smtp_pass - email_smtp_pass
All other configuration changes All other configuration changes
------------------------------- -------------------------------
To be perfectly honest, there are quite a few options and I'm not To be perfectly honest, there are quite a few options and we haven't had
going to be able to get to documanting them all in time for 0.1.0. time to document them all
So here's a cop-out section saying that if you get into trouble, hop So here's a cop-out section saying that if you get into trouble, hop
onto IRC and we'll help you out: onto IRC and we'll help you out::
#mediagoblin on irc.freenode.net #mediagoblin on irc.freenode.net
Celery Celery
====== ======

181
docs/source/deploying.rst
View File

@ -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 mediagoblin + virtualenv + fastcgi + nginx on a .deb or .rpm based
GNU/Linux distro. GNU/Linux distro.
Note: these tools are for administrators wanting to deploy a fresh .. note::
install. If instead you want to join in as a contributor, see our
`Hacking HOWTO <http://wiki.mediagoblin.org/HackingHowto>`_ instead. 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 Prepare System
-------------- --------------
@ -33,12 +35,15 @@ MediaGoblin has the following core dependencies:
On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and
derivatives) issue the following command: :: 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 On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the
following command: :: 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 Configure MongoDB
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
@ -46,10 +51,11 @@ Configure MongoDB
After installing MongoDB some preliminary database configuration may After installing MongoDB some preliminary database configuration may
be necessary. be necessary.
Ensure that MongoDB `journaling <http://www.mongodb.org/display/DOCS/Journaling>`_ Ensure that MongoDB `journaling
is enabled. Journaling is enabled by default in version 2.0 and later <http://www.mongodb.org/display/DOCS/Journaling>`_ is enabled. Journaling
64-bit MongoDB instances. Check your deployment, and consider enabling is enabled by default in version 2.0 and later 64-bit MongoDB instances.
journaling if you're running 32-bit systems or earlier version. Check your deployment, and consider enabling journaling if you're running
32-bit systems or earlier version.
.. warning:: .. 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. not possible to log in to your system with as this user.
You should create a working directory for MediaGoblin. This document You should create a working directory for MediaGoblin. This document
assumes your local git repository will be located at ``/srv/mediagoblin.example.org/mediagoblin/`` assumes your local git repository will be located at
for this documentation. Substitute your prefer ed local deployment path ``/srv/mediagoblin.example.org/mediagoblin/`` for this documentation.
as needed. Substitute your prefer ed local deployment path as needed.
This document assumes that all operations are performed as this This document assumes that all operations are performed as this
user. To drop privileges to this user, run the following command: :: 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. run MediaGoblin.
Install MediaGoblin and Virtualenv Install MediaGoblin and Virtualenv
---------------------------------- ----------------------------------
As of |version|, MediaGoblin has a rapid development pace. As a result .. note::
the following instructions recommend installing from the ``master``
branch of the git repository. Eventually production deployments will As of |version|, MediaGoblin has a rapid development pace. As a result
want to transition to running from more consistent releases. 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 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/ mkdir -p /srv/mediagoblin.example.org/
cd /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 cd mediagoblin
virtualenv . && ./bin/python setup.py develop virtualenv . && ./bin/python setup.py develop
.. note:: .. note::
@ -127,16 +134,16 @@ more reliable and considerably easier to configure and illustrate. If
you're familiar with Python packaging you may consider deploying with you're familiar with Python packaging you may consider deploying with
your preferred the method. your preferred the method.
Assuming you are going to deploy with fastcgi, you should also install Assuming you are going to deploy with FastCGI, you should also install
flup: :: flup::
./bin/easy_install flup ./bin/easy_install flup
This concludes the initial configuration of the development This concludes the initial configuration of the development
environment. In the future, if at any point you want update your 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 Deploy MediaGoblin Services
--------------------------- ---------------------------
@ -145,9 +152,9 @@ Test the Server
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
At this point MediaGoblin should be properly installed. You can 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 You should be able to connect to the machine on port 6543 in your
browser to confirm that the service is operable. browser to confirm that the service is operable.
@ -156,7 +163,7 @@ Connect the Webserver to MediaGoblin with FastCGI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section describes how to configure MediaGoblin to work via 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 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 protocol. If you do not already have a web server, consider nginx, as
the configuration files may be more clear than the the configuration files may be more clear than the
@ -166,78 +173,78 @@ Create a configuration file at
``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link ``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link
into a directory that will be included in your ``nginx`` configuration into a directory that will be included in your ``nginx`` configuration
(e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with (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/conf.d/
ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/ ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/
Modify these commands and locations depending on your preferences and Modify these commands and locations depending on your preferences and
the existing configuration of your nginx instance. The contents of the existing configuration of your nginx instance. The contents of
this ``nginx.conf`` file should be modeled on the following: :: this ``nginx.conf`` file should be modeled on the following::
server { server {
################################################# #################################################
# Stock useful config options, but ignore them :) # Stock useful config options, but ignore them :)
################################################# #################################################
include /etc/nginx/mime.types; include /etc/nginx/mime.types;
autoindex off; autoindex off;
default_type application/octet-stream; default_type application/octet-stream;
sendfile on; sendfile on;
# Gzip # Gzip
gzip on; gzip on;
gzip_min_length 1024; gzip_min_length 1024;
gzip_buffers 4 32k; gzip_buffers 4 32k;
gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css; gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css;
##################################### #####################################
# Mounting MediaGoblin stuff # Mounting MediaGoblin stuff
# This is the section you should read # This is the section you should read
##################################### #####################################
# Change this to update the upload size limit for your users # Change this to update the upload size limit for your users
client_max_body_size 8m; client_max_body_size 8m;
server_name mediagoblin.example.org www.mediagoblin.example.org; server_name mediagoblin.example.org www.mediagoblin.example.org;
access_log /var/log/nginx/mediagoblin.example.access.log; access_log /var/log/nginx/mediagoblin.example.access.log;
error_log /var/log/nginx/mediagoblin.example.error.log; error_log /var/log/nginx/mediagoblin.example.error.log;
# MediaGoblin's stock static files: CSS, JS, etc. # MediaGoblin's stock static files: CSS, JS, etc.
location /mgoblin_static/ { location /mgoblin_static/ {
alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/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 "";
}
} }
# 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 Now, nginx instance is configured to serve the MediaGoblin
application. Perform a quick test to ensure that this configuration application. Perform a quick test to ensure that this configuration
works. Restart nginx so it picks up your changes, with a command that 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/init.d/nginx restart
sudo /etc/rc.d/nginx restart sudo /etc/rc.d/nginx restart
Now start MediaGoblin. Use the following command sequence as an Now start MediaGoblin. Use the following command sequence as an
example: :: example::
cd /srv/mediagoblin.example.org/mediagoblin/ cd /srv/mediagoblin.example.org/mediagoblin/
./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 ./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 Visit the site you've set up in your browser by visiting
<http://mediagobilin.example.org>. You should see MediaGoblin! <http://mediagobilin.example.org>. You should see MediaGoblin!

8
docs/source/foreword.rst
View File

@ -5,14 +5,14 @@ Foreword
About the MediaGoblin Manual About the MediaGoblin Manual
============================ ============================
This is the user manual for MediaGoblin. It covers how to set up and This is the site administrator manual for MediaGoblin. It covers how
configure MediaGoblin and the kind of information that someone running to set up and configure MediaGoblin and the kind of information that
MediaGoblin would need to know. someone running MediaGoblin would need to know.
We have other documentation at: We have other documentation at:
* http://mediagoblin.org/join/ for general "join us" information * http://mediagoblin.org/join/ for general "join us" information
* http://wiki.mediagoblin.org/ for our contributor-focused wiki * http://wiki.mediagoblin.org/ for our contributor/developer-focused wiki
Improving the MediaGobiin Manual Improving the MediaGobiin Manual

29
docs/source/production-deployments.rst
View File

@ -4,8 +4,7 @@ Considerations for Production Deployments
This document contains a number of suggestions for deploying This document contains a number of suggestions for deploying
MediaGoblin in actual production environments. Consider MediaGoblin in actual production environments. Consider
":doc:`deploying`" for a basic overview of how to deploy Media ":doc:`deploying`" for a basic overview of how to deploy MediaGoblin.
Goblin.
Deploy with Paste Deploy with Paste
----------------- -----------------
@ -17,11 +16,11 @@ process.
Use the following command as the basis for such a script: :: Use the following command as the basis for such a script: ::
CELERY_ALWAYS_EAGER=true \ CELERY_ALWAYS_EAGER=true \
/srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
/srv/mediagoblin.example.org/mediagoblin/paste.ini \ /srv/mediagoblin.example.org/mediagoblin/paste.ini \
--pid-file=/var/run/mediagoblin.pid \ --pid-file=/var/run/mediagoblin.pid \
--server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 \ --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
The above configuration places MediaGoblin in "always eager" mode The above configuration places MediaGoblin in "always eager" mode
with Celery, this means that submissions of content will be processed with Celery, this means that submissions of content will be processed
@ -31,11 +30,11 @@ the user will be able to immediately return to the MediaGoblin site
while processing is ongoing. In these cases, use the following command while processing is ongoing. In these cases, use the following command
as the basis for your script: :: as the basis for your script: ::
CELERY_ALWAYS_EAGER=false \ CELERY_ALWAYS_EAGER=false \
/srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
/srv/mediagoblin.example.org/mediagoblin/paste.ini \ /srv/mediagoblin.example.org/mediagoblin/paste.ini \
--pid-file=/var/run/mediagoblin.pid \ --pid-file=/var/run/mediagoblin.pid \
--server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 \ --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
Separate Celery Separate Celery
--------------- ---------------
@ -57,9 +56,9 @@ such as "ASCII art" or icon sharing, you will need to run ``celeryd``
as a separate process. as a separate process.
Build an :ref:`init script <init-script>` around the following Build an :ref:`init script <init-script>` around the following
command. command::
CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd
Modify your existing MediaGoblin and application init scripts, if Modify your existing MediaGoblin and application init scripts, if
necessary, to prevent them from starting their own ``celeryd`` necessary, to prevent them from starting their own ``celeryd``
@ -77,6 +76,6 @@ distribution/operating system. In the future, MediaGoblin will provide
example scripts as examples. example scripts as examples.
.. TODO insert init script here .. TODO insert init script here
.. TODO are additional concernts ? .. TODO are additional concerns ?
.. Other Concerns .. Other Concerns
.. -------------- .. --------------