diff options
Diffstat (limited to 'docs/source/siteadmin')
| -rw-r--r-- | docs/source/siteadmin/about.rst | 101 | ||||
| -rw-r--r-- | docs/source/siteadmin/codebase.rst | 160 | ||||
| -rw-r--r-- | docs/source/siteadmin/configuration.rst | 129 | ||||
| -rw-r--r-- | docs/source/siteadmin/deploying.rst | 320 | ||||
| -rw-r--r-- | docs/source/siteadmin/foreword.rst | 48 | ||||
| -rw-r--r-- | docs/source/siteadmin/help.rst | 29 | ||||
| -rw-r--r-- | docs/source/siteadmin/media-types.rst | 76 | ||||
| -rw-r--r-- | docs/source/siteadmin/plugins.rst | 137 | ||||
| -rw-r--r-- | docs/source/siteadmin/production-deployments.rst | 94 | ||||
| -rw-r--r-- | docs/source/siteadmin/relnotes.rst | 52 | ||||
| -rw-r--r-- | docs/source/siteadmin/theming.rst | 21 |
11 files changed, 1167 insertions, 0 deletions
diff --git a/docs/source/siteadmin/about.rst b/docs/source/siteadmin/about.rst new file mode 100644 index 00000000..95647abb --- /dev/null +++ b/docs/source/siteadmin/about.rst @@ -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/ diff --git a/docs/source/siteadmin/codebase.rst b/docs/source/siteadmin/codebase.rst new file mode 100644 index 00000000..3ef91290 --- /dev/null +++ b/docs/source/siteadmin/codebase.rst @@ -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. diff --git a/docs/source/siteadmin/configuration.rst b/docs/source/siteadmin/configuration.rst new file mode 100644 index 00000000..a3dafa4c --- /dev/null +++ b/docs/source/siteadmin/configuration.rst @@ -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 :) diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst new file mode 100644 index 00000000..788b06d7 --- /dev/null +++ b/docs/source/siteadmin/deploying.rst @@ -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. diff --git a/docs/source/siteadmin/foreword.rst b/docs/source/siteadmin/foreword.rst new file mode 100644 index 00000000..4c425f8d --- /dev/null +++ b/docs/source/siteadmin/foreword.rst @@ -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. + diff --git a/docs/source/siteadmin/help.rst b/docs/source/siteadmin/help.rst new file mode 100644 index 00000000..4b584ac1 --- /dev/null +++ b/docs/source/siteadmin/help.rst @@ -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/ + + diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst new file mode 100644 index 00000000..1cf7f30c --- /dev/null +++ b/docs/source/siteadmin/media-types.rst @@ -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! diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst new file mode 100644 index 00000000..41f2970f --- /dev/null +++ b/docs/source/siteadmin/plugins.rst @@ -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. diff --git a/docs/source/siteadmin/production-deployments.rst b/docs/source/siteadmin/production-deployments.rst new file mode 100644 index 00000000..1e6631db --- /dev/null +++ b/docs/source/siteadmin/production-deployments.rst @@ -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 + .. -------------- diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst new file mode 100644 index 00000000..2efded73 --- /dev/null +++ b/docs/source/siteadmin/relnotes.rst @@ -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. diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst new file mode 100644 index 00000000..7584b688 --- /dev/null +++ b/docs/source/siteadmin/theming.rst @@ -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. |