heckyel/mediagoblin
0
0
Fork 0
Code Issues Pull Requests Releases Activity

Split docs into siteadmin and pluginwriter guides

Browse Source 
* create initial bits for plugin writer's guide
* move siteadmin stuff to site administrator's guide
* rework index.rst to support multiple guides
* tweak some text
* move files into subdirectories

I verified that this still works with html and texinfo build targets.
There's still a lot of work to do, but this is a good start.
This commit is contained in:
Will Kahn-Greene
2012-05-23 20:21:03 -04:00
parent 758def22b8
commit 2530ef7a1f
15 changed files with 80 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
docs/source/siteadmin/about.rst Normal file
View File

@@ -0,0 +1,101 @@
.. MediaGoblin Documentation
Written in 2011, 2012 by MediaGoblin contributors
To the extent possible under law, the author(s) have dedicated all
copyright and related and neighboring rights to this software to
the public domain worldwide. This software is distributed without
any warranty.
You should have received a copy of the CC0 Public Domain
Dedication along with this software. If not, see
<http://creativecommons.org/publicdomain/zero/1.0/>.
=======================
About GNU MediaGoblin
=======================
.. contents:: Sections
:local:
What is GNU MediaGoblin?
========================
In 2008, a number of free software developers and activists gathered
at the FSF to attempt to answer the question "What should software
freedom look like on the participatory web?" Their answer, the
`Franklin Street Statement`_ has lead to the development of
`autonomo.us`_ community, and free software projects including
`Identi.ca`_ and `Libre.fm`_.
.. _Franklin Street Statement: http://autonomo.us/2008/07/franklin-street-statement/
.. _autonomo.us: http://autonomo.us/
.. _identi.ca: http://identi.ca/
.. _Libre.fm: http://libre.fm/
Identi.ca and Libre.fm address the need for micro-blogging and music
sharing services and software that respect users' freedom and
autonomy. GNU MediaGoblin emerges from this milieu to create a
platform for us to share photos in an environment that respects our
freedom and independence. In the future MediaGoblin will include
support other media, like video, and provide tools to facilitate
collaboration on media projects.
Why Build GNU MediaGoblin?
==========================
The Internet is designed---and works best---as a complex and endlessly
resilient network. When key services and media outlets are
concentrated in centralized platforms, the network becomes less useful
and increasingly fragile. As always, the proprietary nature of these
systems, hinders users ability to develop, extend, and understand
their software; however, in the case of network services it also means
that users must forfeit control of their data to the service
providers.
Therefore, we believe that network services must be federated to avoid
centralization and that everyone ought to have control over their
data. In support of this, we've decided to help build the tools to
make these kinds of services possible. We hope you'll join us, both
as users and as contributors.
Who Contributes to the Project?
===============================
You do!
We are free software activists and folks who have worked on a variety
of other projects including: Libre.fm, GNU Social, Status.net, Miro,
Miro Community, and OpenHatch among others. We're programmers,
musicians, writers, and painters. We're friendly and dedicated to
software and network freedom.
How Can I Participate?
======================
See `Get Involved <http://mediagoblin.org/join/>`_ on the website. We
eagerly look forward to seeing you!
How is GNU MediaGoblin licensed?
================================
GNU MediaGoblin software is released under an AGPLv3 license.
See the ``COPYING`` file in the root of the source for details.
Is MediaGoblin an official GNU project? What does that mean?
=============================================================
MediaGoblin is an official GNU project! This status means that we the
meet the GNU Project's rigorous standards for free software. To find
out more about what that means, check out the `GNU website`_.
Please feel free to contact us with further questions!
.. _GNU website: http://gnu.org/

160
docs/source/siteadmin/codebase.rst Normal file
View File

@@ -0,0 +1,160 @@
.. MediaGoblin Documentation
Written in 2011, 2012 by MediaGoblin contributors
To the extent possible under law, the author(s) have dedicated all
copyright and related and neighboring rights to this software to
the public domain worldwide. This software is distributed without
any warranty.
You should have received a copy of the CC0 Public Domain
Dedication along with this software. If not, see
<http://creativecommons.org/publicdomain/zero/1.0/>.
.. _codebase-chapter:
========================
Codebase Documentation
========================
.. contents:: Sections
:local:
This chapter covers the libraries that GNU MediaGoblin uses as well as
various recipes for getting things done.
.. Note::
This chapter is in flux. Clearly there are things here that aren't
documented. If there's something you have questions about, please
ask!
See `the join page on the website <http://mediagoblin.org/join/>`_
for where we hang out.
For more information on how to get started hacking on GNU MediaGoblin,
see `the wiki <http://wiki.mediagoblin.org/>`_.
Software Stack
==============
* Project infrastructure
* `Python <http://python.org/>`_: the language we're using to write
this
* `Nose <http://somethingaboutorange.com/mrl/projects/nose/>`_:
for unit tests
* `virtualenv <http://www.virtualenv.org/>`_: for setting up an
isolated environment to keep mediagoblin and related packages
(potentially not required if MediaGoblin is packaged for your
distro)
* Data storage
* `SQLAlchemy <http://sqlalchemy.org/>`_: SQL ORM and database
interaction library for Python. Currently we support sqlite and
postgress as backends.
* Web application
* `Paste Deploy <http://pythonpaste.org/deploy/>`_ and
`Paste Script <http://pythonpaste.org/script/>`_: we'll use this for
configuring and launching the application
* `WebOb <http://pythonpaste.org/webob/>`_: nice abstraction layer
from HTTP requests, responses and WSGI bits
* `Routes <http://routes.groovie.org/>`_: for URL routing
* `Beaker <http://beaker.groovie.org/>`_: for handling sessions and
caching
* `Jinja2 <http://jinja.pocoo.org/docs/>`_: the templating engine
* `WTForms <http://wtforms.simplecodes.com/>`_: for handling,
validation, and abstraction from HTML forms
* `Celery <http://celeryproject.org/>`_: for task queuing (resizing
images, encoding video, ...)
* `Babel <http://babel.edgewall.org>`_: Used to extract and compile
translations.
* `Markdown (for python) <http://pypi.python.org/pypi/Markdown>`_:
implementation of `Markdown <http://daringfireball.net/projects/markdown/>`_
text-to-html tool to make it easy for people to write richtext
comments, descriptions, and etc.
* `lxml <http://lxml.de/>`_: nice xml and html processing for
python.
* Media processing libraries
* `Python Imaging Library <http://www.pythonware.com/products/pil/>`_:
used to resize and otherwise convert images for display.
* `GStreamer <http://gstreamer.freedesktop.org/>`_: (Optional, for
video hosting sites only) Used to transcode video, and in the
future, probably audio too.
* `chardet <http://pypi.python.org/pypi/chardet>`_: (Optional, for
ascii art hosting sites only) Used to make ascii art thumbnails.
* Front end
* `JQuery <http://jquery.com/>`_: for groovy JavaScript things
What's where
============
After you've run checked out mediagoblin and followed the virtualenv
instantiation instructions, you're faced with the following directory
tree::
mediagoblin/
|- mediagoblin/ # source code
| |- tests/
| |- templates/
| |- auth/
| \- submit/
|- docs/ # documentation
|- devtools/ # some scripts for developer convenience
|
| # the below directories are installed into your virtualenv checkout
|
|- bin/ # scripts
|- develop-eggs/
|- lib/ # python libraries installed into your virtualenv
|- include/
|- mediagoblin.egg-info/
|- parts/
|- user_dev/ # sessions, etc
As you can see, all the code for GNU MediaGoblin is in the
``mediagoblin`` directory.
Here are some interesting files and what they do:
:routing.py: maps url paths to views
:views.py: views handle http requests
:models.py: holds the sqlalchemy schemas---these are the data structures
we're working with
You'll notice that there are several sub-directories: tests,
templates, auth, submit, ...
``tests`` holds the unit test code.
``templates`` holds all the templates for the output.
``auth`` and ``submit`` are modules that enacpsulate authentication
and media item submission. If you look in these directories, you'll
see they have their own ``routing.py``, ``view.py``, and
``models.py`` in addition to some other code.

129
docs/source/siteadmin/configuration.rst Normal file
View File

@@ -0,0 +1,129 @@
.. MediaGoblin Documentation
Written in 2011, 2012 by MediaGoblin contributors
To the extent possible under law, the author(s) have dedicated all
copyright and related and neighboring rights to this software to
the public domain worldwide. This software is distributed without
any warranty.
You should have received a copy of the CC0 Public Domain
Dedication along with this software. If not, see
<http://creativecommons.org/publicdomain/zero/1.0/>.
.. _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::
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 email. By default,
MediaGoblin doesn't really do this... for the sake of developer
convenience, it runs in "email debug mode".
To make MediaGoblin send email, you need a mailer daemon.
Change this in your ``mediagoblin.ini`` file::
email_debug_mode = false
You should also change the "from" email address by setting
``email_sender_address``. For example::
email_sender_address = "foo@example.com"
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 we haven't had
time to document them all.
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 :)

320
docs/source/siteadmin/deploying.rst Normal file
View File

@@ -0,0 +1,320 @@
.. MediaGoblin Documentation
Written in 2011, 2012 by MediaGoblin contributors
To the extent possible under law, the author(s) have dedicated all
copyright and related and neighboring rights to this software to
the public domain worldwide. This software is distributed without
any warranty.
You should have received a copy of the CC0 Public Domain
Dedication along with this software. If not, see
<http://creativecommons.org/publicdomain/zero/1.0/>.
.. _deploying-chapter:
=====================
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.
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.
.. 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
--------------
Dependencies
~~~~~~~~~~~~
MediaGoblin has the following core dependencies:
- Python 2.6 or 2.7
- `python-lxml <http://lxml.de/>`_
- `git <http://git-scm.com/>`_
- `SQLite <http://www.sqlite.org/>`_/`PostgreSQL <http://www.postgresql.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 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 python-paste-deploy python-paste-script \
git-core python python-devel python-lxml python-imaging \
python-virtualenv
Configure PostgreSQL
~~~~~~~~~~~~~~~~~~~~
.. note::
MediaGoblin currently supports PostgreSQL and SQLite. The default is a
local SQLite database. This will "just work" for small deployments.
For medium to large deployments we recommend PostgreSQL.
If you don't want/need postgres, skip this section.
These are the packages needed for Debian Wheezy (testing)::
sudo apt-get install postgresql postgresql-client python-psycopg2
The installation process will create a new *system* user named ``postgres``,
it will have privilegies sufficient to manage the database. We will create a
new database user with restricted privilegies and a new database owned by our
restricted database user for our MediaGoblin instance.
In this example, the database user will be ``mediagoblin`` and the database
name will be ``mediagoblin`` too.
To create our new user, run::
sudo -u postgres createuser mediagoblin
then answer NO to *all* the questions::
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) n
Shall the new role be allowed to create more new roles? (y/n) n
then create the database all our MediaGoblin data should be stored in::
sudo -u postgres createdb -E UNICODE -O mediagoblin mediagoblin
where the first ``mediagoblin`` is the database owner and the second
``mediagoblin`` is the database name.
.. caution:: Where is the password?
These steps enable you to authenticate to the database in a password-less
manner via local UNIX authentication provided you run the MediaGoblin
application as a user with the same name as the user you created in
PostgreSQL.
More on this in :ref:`Drop Privileges for MediaGoblin <drop-privileges-for-mediagoblin>`.
.. _drop-privileges-for-mediagoblin:
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
----------------------------------
.. note::
MediaGoblin is still developing rapidly. 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 set up the in-package virtualenv::
cd mediagoblin
(virtualenv --system-site-packages . || 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, you want update your
codebase, you should also run::
./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate
Deploy MediaGoblin Services
---------------------------
Configure MediaGoblin to use the PostgreSQL database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you are using postgres, edit the ``[mediagoblin]`` section in your
``mediagoblin_local.ini`` and put in::
sql_engine = postgresql:///mediagoblin
if you are running the MediaGoblin application as the same 'user' as the
database owner.
Update database data structures
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before you start using the database, you need to run::
./bin/gmg dbupdate
to populate the database with the MediaGoblin data structures.
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
#####################################
# 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)::
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://mediagoblin.example.org>. You should see MediaGoblin!
.. note::
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.

48
docs/source/siteadmin/foreword.rst Normal file
View File

@@ -0,0 +1,48 @@
.. MediaGoblin Documentation
Written in 2011, 2012 by MediaGoblin contributors
To the extent possible under law, the author(s) have dedicated all
copyright and related and neighboring rights to this software to
the public domain worldwide. This software is distributed without
any warranty.
You should have received a copy of the CC0 Public Domain
Dedication along with this software. If not, see
<http://creativecommons.org/publicdomain/zero/1.0/>.
========
Foreword
========
About the Site Administrator's Guide
====================================
This is the site administrator manual for GNU MediaGoblin. It covers
how to set up and configure MediaGoblin and the kind of information
that someone running MediaGoblin would need to know.
We have other documentation at:
* http://mediagoblin.org/join/ for general "join us" information
* http://wiki.mediagoblin.org/ for our contributor/developer-focused wiki
Improving the Site Administrator's Guide
========================================
There are a few ways---please pick whichever method is convenient for
you!
1. Write up a bug report in the bug tracker
2. Tell someone on IRC ``#mediagoblin`` on Freenode.
3. Write an email to the devel mailing list.
Information about the bugtracker, IRC and the mailing list is all on
the `join page`_.
.. _join page: http://mediagoblin.org/join/
Patches are the most helpful, but even feedback on what you think
could be improved and how to improve it is also helpful.

29
docs/source/siteadmin/help.rst Normal file
View File

@@ -0,0 +1,29 @@
.. MediaGoblin Documentation
Written in 2011, 2012 by MediaGoblin contributors
To the extent possible under law, the author(s) have dedicated all
copyright and related and neighboring rights to this software to
the public domain worldwide. This software is distributed without
any warranty.
You should have received a copy of the CC0 Public Domain
Dedication along with this software. If not, see
<http://creativecommons.org/publicdomain/zero/1.0/>.
==================================
How to Get Help with MediaGoblin
==================================
There are a couple of ways to get help with problems with MediaGoblin:
1. ask for help on IRC
2. ask for help on the devel mailing list
Details for both IRC and the mailing list are on the `join page`_ of the
website.
.. _join page: http://mediagoblin.org/join/

76
docs/source/siteadmin/media-types.rst Normal file
View File

@@ -0,0 +1,76 @@
.. MediaGoblin Documentation
Written in 2011, 2012 by MediaGoblin contributors
To the extent possible under law, the author(s) have dedicated all
copyright and related and neighboring rights to this software to
the public domain worldwide. This software is distributed without
any warranty.
You should have received a copy of the CC0 Public Domain
Dedication along with this software. If not, see
<http://creativecommons.org/publicdomain/zero/1.0/>.
.. _media-types-chapter:
====================
Enabling Media Types
====================
In the future, there will be all sorts of media types you can enable,
but in the meanwhile there are two additional media type: video and
ascii art.
First, you should probably read ":doc:`configuration`" to make sure
you know how to modify the mediagoblin config file.
Video
=====
To enable video, first install gstreamer and the python-gstreamer
bindings (as well as whatever gstremaer extensions you want,
good/bad/ugly). On Debianoid systems::
sudo apt-get install python-gst0.10 gstreamer0.10-plugins-{base,bad,good,ugly} \
gstreamer0.10-ffmpeg
Next, modify (and possibly copy over from ``mediagoblin.ini``) your
``mediagoblin_local.ini``. In the ``[mediagoblin]`` section, add
``mediagoblin.media_types.video`` to the ``media_types`` list.
For example, if your system supported image and video media types, then
the list would look like this::
media_types = mediagoblin.media_types.image, mediagoblin.media_types.video
Now you should be able to submit videos, and mediagoblin should
transcode them.
.. note::
You almost certainly want to separate Celery from the normal
paste process or your users will probably find that their connections
time out as the video transcodes. To set that up, check out the
":doc:`production-deployments`" section of this manual.
Ascii art
=========
To enable ascii art support, first install the
`chardet <http://pypi.python.org/pypi/chardet>`_
library, which is necessary for creating thumbnails of ascii art::
./bin/easy_install chardet
Next, modify (and possibly copy over from ``mediagoblin.ini``) your
``mediagoblin_local.ini``. In the ``[mediagoblin]`` section, add
``mediagoblin.media_types.ascii`` to the ``media_types`` list.
For example, if your system supported image and ascii art media types, then
the list would look like this::
media_types = mediagoblin.media_types.image, mediagoblin.media_types.ascii
Now any .txt file you uploaded will be processed as ascii art!

137
docs/source/siteadmin/plugins.rst Normal file
View File

@@ -0,0 +1,137 @@
=========
Plugins
=========
GNU MediaGoblin supports plugins that allow you to augment MediaGoblin's
behavior.
This chapter covers discovering, installing, configuring and removing
plugins.
Discovering plugins
===================
MediaGoblin comes with core plugins. Core plugins are located in the
``mediagoblin.plugins`` module of the MediaGoblin code. Because they
come with MediaGoblin, you don't have to install them, but you do have
to add them to your config file if you're interested in using them.
You can also write your own plugins and additionally find plugins
elsewhere on the Internet. Once you find a plugin you like, you need
to first install it, then add it to your configuration.
.. todo: how do you find plugins on the internet?
Installing plugins
==================
Core plugins
------------
MediaGoblin core plugins don't need to be installed because they come
with MediaGoblin. Further, when you upgrade MediaGoblin, you will also
get updates to the core plugins.
Other plugins
-------------
If the plugin is available on the `Python Package Index
<http://pypi.python.org/pypi>`_, then you can install the plugin with pip::
pip install <plugin-name>
For example, if we wanted to install the plugin named
"mediagoblin-restrictfive", we would do::
pip install mediagoblin-restrictfive
.. Note::
If you're using a virtual environment, make sure to activate the
virtual environment before installing with pip. Otherwise the
plugin may get installed in a different environment than the one
MediaGoblin is installed in.
Once you've installed the plugin software, you need to tell
MediaGoblin that this is a plugin you want MediaGoblin to use. To do
that, you edit the ``mediagoblin.ini`` file and add the plugin as a
subsection of the plugin section.
For example, say the "mediagoblin-restrictfive" plugin had the Python
package path ``restrictfive``, then you would add ``restrictfive`` to
the ``plugins`` section as a subsection::
[plugins]
[[restrictfive]]
Configuring plugins
===================
Configuration for a plugin goes in the subsection for that plugin. Core
plugins are documented in the administration guide. Other plugins
should come with documentation that tells you how to configure them.
Example 1: Core MediaGoblin plugin
If you wanted to use the core MediaGoblin flatpages plugin, the module
for that is ``mediagoblin.plugins.flatpages`` and you would add that
to your ``.ini`` file like this::
[plugins]
[[mediagoblin.plugins.flatpages]]
# configuration for flatpages plugin here!
directory = /srv/mediagoblin/flatpages
Example 2: Plugin that is not a core MediaGoblin plugin
If you installed a hypothetical restrictfive plugin which is in the
module ``restrictfive``, your ``.ini`` file might look like this (with
comments making the bits clearer)::
[plugins]
[[restrictfive]]
# configuration for restrictfive here!
Check the plugin's documentation for what configuration options are
available.
Removing plugins
================
To remove a plugin, use ``pip uninstall``. For example::
pip uninstall mediagoblin-restrictfive
.. Note::
If you're using a virtual environment, make sure to activate the
virtual environment before uninstalling with pip. Otherwise the
plugin may get installed in a different environment.
Upgrading plugins
=================
Core plugins
------------
Core plugins get upgraded automatically when you upgrade MediaGoblin
because they come with MediaGoblin.
Other plugins
-------------
For plugins that you install with pip, you can upgrade them with pip::
pip install -U <plugin-name>
The ``-U`` tells pip to upgrade the package.

94
docs/source/siteadmin/production-deployments.rst Normal file
View File

@@ -0,0 +1,94 @@
.. MediaGoblin Documentation
Written in 2011, 2012 by MediaGoblin contributors
To the extent possible under law, the author(s) have dedicated all
copyright and related and neighboring rights to this software to
the public domain worldwide. This software is distributed without
any warranty.
You should have received a copy of the CC0 Public Domain
Dedication along with this software. If not, see
<http://creativecommons.org/publicdomain/zero/1.0/>.
=========================================
Considerations for Production Deployments
=========================================
This document contains a number of suggestions for deploying
MediaGoblin in actual production environments. Consider
":doc:`deploying`" for a basic overview of how to deploy MediaGoblin.
Deploy with Paste
-----------------
The instance configured with ``./lazyserver.sh`` is not ideal for a
production MediaGoblin deployment. Ideally, you should be able to use
an "init" or "control" 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=/var/run/mediagoblin.pid \
--server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
The above configuration places MediaGoblin in "always eager" mode
with Celery, this means that submissions of content will be processed
synchronously, and the user will advance to the next page only after
processing is complete. If we take Celery out of "always eager mode,"
the user will be able to immediately return to the MediaGoblin site
while processing is ongoing. In these cases, use the following command
as the basis for your script: ::
CELERY_ALWAYS_EAGER=false \
/srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
/srv/mediagoblin.example.org/mediagoblin/paste.ini \
--pid-file=/var/run/mediagoblin.pid \
--server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
Separate Celery
---------------
While the ``./lazyserer.sh`` configuration provides an efficient way to
start using a MediaGoblin instance, it is not suitable for production
deployments for several reasons:
In nearly every scenario, work on the Celery queue will need to
balance with the demands of other processes, and cannot proceed
synchronously. This is a particularly relevant problem if you use
MediaGoblin to host video content. Processing with Celery ought to be
operationally separate from the MediaGoblin application itself, this
simplifies management and support better workload distribution.
Basically, if you're doing anything beyond a trivial workload, such as
image hosting for a small set of users, or have limited media types
such as "ASCII art" or icon sharing, you will need to run ``celeryd``
as a separate process.
Build an :ref:`init script <init-script>` around the following
command::
CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd
Modify your existing MediaGoblin and application init scripts, if
necessary, to prevent them from starting their own ``celeryd``
processes.
.. _init-script:
Use an Init Script
------------------
Look in your system's ``/etc/init.d/`` or ``/etc/rc.d/`` directory for
examples of how to build scripts that will start, stop, and restart
MediaGoblin and Celery. These scripts will vary by
distribution/operating system. In the future, MediaGoblin will provide
example scripts as examples.
.. TODO insert init script here
.. TODO are additional concerns ?
.. Other Concerns
.. --------------

52
docs/source/siteadmin/relnotes.rst Normal file
View File

@@ -0,0 +1,52 @@
.. MediaGoblin Documentation
Written in 2012 by MediaGoblin contributors
To the extent possible under law, the author(s) have dedicated all
copyright and related and neighboring rights to this software to
the public domain worldwide. This software is distributed without
any warranty.
You should have received a copy of the CC0 Public Domain
Dedication along with this software. If not, see
<http://creativecommons.org/publicdomain/zero/1.0/>.
=============
Release Notes
=============
This chapter has important information for releases in it.
If you're upgrading from a previous release, please read it
carefully, or at least skim over it.
0.3.0
=====
This release has one important change. You need to act when
upgrading from a previous version!
This release changes the database system from MongoDB to
SQL(alchemy). If you want to setup a fresh instance, just
follow the instructions in the deployment chapter. If on
the other hand you want to continue to use one instance,
read on.
To convert your data from MongoDB to SQL(alchemy), you need
to follow these steps:
1. Make sure your MongoDB is still running and has your
data, it's needed for the conversion.
2. Configure the ``sql_engine`` URI in the config to represent
your target database (see: :ref:`deploying-chapter`)
3. You need an empty database.
4. Then run the following command::
bin/gmg [-cf mediagoblin_config.ini] convert_mongo_to_sql
5. Start your server and investigate.
6. That's it.

21
docs/source/siteadmin/theming.rst Normal file
View File

@@ -0,0 +1,21 @@
.. MediaGoblin Documentation
Written in 2011, 2012 by MediaGoblin contributors
To the extent possible under law, the author(s) have dedicated all
copyright and related and neighboring rights to this software to
the public domain worldwide. This software is distributed without
any warranty.
You should have received a copy of the CC0 Public Domain
Dedication along with this software. If not, see
<http://creativecommons.org/publicdomain/zero/1.0/>.
.. _theming-chapter:
=====================
Theming MediaGoblin
=====================
We haven't implemented the necessary scaffolding to allow for theming
yet. Thus, this chapter is a stub.