Merge remote-tracking branch 'cweb/master'

10 files changed, 1836 insertions, 0 deletions

diff --git a/docs/source/siteadmin/about.rst b/docs/source/siteadmin/about.rst
new file mode 100644
index 00000000..f9602397
--- /dev/null
+++ b/docs/source/siteadmin/about.rst
@@ -0,0 +1,102 @@
+.. 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, video and other media in an environment that respects our freedom and
+independence.  In the future MediaGoblin will 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/configuration.rst b/docs/source/siteadmin/configuration.rst
new file mode 100644
index 00000000..3da5cdd9
--- /dev/null
+++ b/docs/source/siteadmin/configuration.rst
@@ -0,0 +1,131 @@
+.. 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.  Details for the IRC channel is on the
+`join page`_ of the website.
+
+.. _join page: http://mediagoblin.org/join/
+
+
+
+
+Celery
+======
+
+FIXME: List Celery configuration here.
diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst
new file mode 100644
index 00000000..0ee6b5b4
--- /dev/null
+++ b/docs/source/siteadmin/deploying.rst
@@ -0,0 +1,390 @@
+.. 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.
+
+   There are also many ways to install servers... for the sake of
+   simplicity, our instructions below describe installing with nginx.
+   For more recipes, including Apache, see
+   `our wiki <http://wiki.mediagoblin.org/Deployment>`_.
+
+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 may 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 method.
+
+Assuming you are going to deploy with FastCGI, you should also install
+flup::
+
+    ./bin/easy_install flup
+
+(Sometimes this breaks because flup's site is flakey.  If it does for
+you, try)::
+
+    ./bin/easy_install https://pypi.python.org/pypi/flup/1.0.3.dev-20110405
+
+This concludes the initial configuration of the development
+environment. In the future, when you update your
+codebase, you should also run::
+
+    ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate
+
+Note: If you are running an active site, depending on your server
+configuration, you may need to stop it first or the dbupdate command
+may hang (and it's certainly a good idea to restart it after the
+update)
+
+
+Deploy MediaGoblin Services
+---------------------------
+
+Edit site configuration
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A few basic properties must be set before MediaGoblin will work. First
+make a copy of ``mediagoblin.ini`` for editing so the original config
+file isn't lost::
+
+    cp mediagoblin.ini mediagoblin_local.ini
+
+Then:
+ - Set ``email_sender_address`` to the address you wish to be used as
+   the sender for system-generated emails
+ - Edit ``direct_remote_path``, ``base_dir``, and ``base_url`` if
+   your mediagoblin directory is not the root directory of your
+   vhost.
+
+
+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.
+
+.. _webserver-config:
+
+
+FastCGI and nginx
+~~~~~~~~~~~~~~~~~
+
+This 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;
+
+     # prevent attacks (someone uploading a .txt file that the browser
+     # interprets as an HTML file, etc.)
+     add_header X-Content-Type-Options nosniff;
+
+     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/;
+     }
+
+     # Theme static files (usually symlinked in)
+     location /theme_static/ {
+        alias /srv/mediagoblin.example.org/mediagoblin/user_dev/theme_static/;
+     }
+
+     # Plugin static files (usually symlinked in)
+     location /plugin_static/ {
+        alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/;
+     }
+
+     # 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.
+   
+
+Apache
+~~~~~~
+
+Instructions and scripts for running MediaGoblin on an Apache server
+can be found on the `MediaGoblin wiki <http://wiki.mediagoblin.org/Deployment>`_.
+
+
+Security Considerations
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning::
+
+   The directory ``user_dev/crypto/`` contains some very
+   sensitive files.
+   Especially the ``itsdangeroussecret.bin`` is very important
+   for session security. Make sure not to leak its contents anywhere.
+   If the contents gets leaked nevertheless, delete your file
+   and restart the server, so that it creates a new secret key.
+   All previous sessions will be invalifated then.
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..1527bc70
--- /dev/null
+++ b/docs/source/siteadmin/media-types.rst
@@ -0,0 +1,245 @@
+.. 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:
+
+====================
+Media Types
+====================
+
+In the future, there will be all sorts of media types you can enable,
+but in the meanwhile there are three additional media types: video, audio
+and ascii art.
+
+First, you should probably read ":doc:`configuration`" to make sure
+you know how to modify the mediagoblin config file.
+
+
+Enabling Media Types
+====================
+
+Media types are enabled in your mediagoblin configuration file, typically it is
+created by copying ``mediagoblin.ini`` to ``mediagoblin_local.ini`` and then
+applying your changes to ``mediagoblin_local.ini``. If you don't already have a
+``mediagoblin_local.ini``, create one in the way described.
+
+Most media types have additional dependencies that you will have to install.
+You will find descriptions on how to satisfy the requirements of each media type
+on this page.
+
+To enable a media type, edit the ``media_types`` list in your
+``mediagoblin_local.ini``. 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
+
+Note that after enabling new media types, you must run dbupdate like so::
+
+    ./bin/gmg dbupdate
+
+If you are running an active site, depending on your server
+configuration, you may need to stop it first (and it's certainly a
+good idea to restart it after the update).
+
+
+How does MediaGoblin decide which media type to use for a file?
+===============================================================
+
+MediaGoblin has two methods for finding the right media type for an uploaded
+file. One is based on the file extension of the uploaded file; every media type
+maintains a list of supported file extensions. The second is based on a sniffing
+handler, where every media type may inspect the uploaded file and tell if it
+will accept it.
+
+The file-extension-based approach is used before the sniffing-based approach,
+if the file-extension-based approach finds a match, the sniffing-based approach
+will be skipped as it uses far more processing power.
+
+
+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
+
+.. code-block:: bash
+
+    sudo apt-get install python-gst0.10 \
+        gstreamer0.10-plugins-base \
+        gstreamer0.10-plugins-bad \
+        gstreamer0.10-plugins-good \
+        gstreamer0.10-plugins-ugly \
+        gstreamer0.10-ffmpeg
+
+
+Add ``mediagoblin.media_types.video`` to the ``media_types`` list in your
+``mediagoblin_local.ini`` and restart MediaGoblin.
+
+Run
+
+.. code-block:: bash
+
+    ./bin/gmg dbupdate
+
+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.
+
+
+Audio
+=====
+
+To enable audio, install the gstreamer and python-gstreamer bindings (as well
+as whatever gstreamer plugins you want, good/bad/ugly), scipy and numpy are
+also needed for the audio spectrograms.
+To install these on Debianoid systems, run::
+
+    sudo apt-get install python-gst0.10 gstreamer0.10-plugins-{base,bad,good,ugly} \
+        gstreamer0.10-ffmpeg python-numpy python-scipy
+
+The ``scikits.audiolab`` package you will install in the next step depends on the
+``libsndfile1-dev`` package, so we should install it.
+On Debianoid systems, run
+
+.. code-block:: bash
+
+    sudo apt-get install libsndfile1-dev
+
+.. note::
+    scikits.audiolab will display a warning every time it's imported if you do
+    not compile it with alsa support. Alsa support is not necessary for the GNU
+    MediaGoblin application but if you do not wish the alsa warnings from
+    audiolab you should also install ``libasound2-dev`` before installing
+    scikits.audiolab.
+
+Then install ``scikits.audiolab`` for the spectrograms::
+
+    ./bin/pip install scikits.audiolab
+
+Add ``mediagoblin.media_types.audio`` to the ``media_types`` list in your
+``mediagoblin_local.ini`` and restart MediaGoblin.
+
+Run
+
+.. code-block:: bash
+
+    ./bin/gmg dbupdate
+
+You should now be able to upload and listen to audio files!
+
+
+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
+
+.. code-block:: bash
+
+    ./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
+
+Run
+
+.. code-block:: bash
+
+    ./bin/gmg dbupdate
+
+Now any .txt file you uploaded will be processed as ascii art!
+
+
+STL / 3d model support
+======================
+
+To enable the "STL" 3d model support plugin, first make sure you have
+a recentish `Blender <http://blender.org>`_ installed and available on
+your execution path.  This feature has been tested with Blender 2.63.
+It may work on some earlier versions, but that is not guaranteed (and
+is surely not to work prior to Blender 2.5X).
+
+Add ``mediagoblin.media_types.stl`` to the ``media_types`` list in your
+``mediagoblin_local.ini`` and restart MediaGoblin. 
+
+Run
+
+.. code-block:: bash
+
+    ./bin/gmg dbupdate
+
+You should now be able to upload .obj and .stl files and MediaGoblin
+will be able to present them to your wide audience of admirers!
+
+PDF and Document
+================
+
+To enable the "PDF and Document" support plugin, you need:
+
+1. pdftocairo and pdfinfo for pdf only support.
+
+2. unoconv with headless support to support converting libreoffice supported
+   documents as well, such as doc/ppt/xls/odf/odg/odp and more.
+   For the full list see mediagoblin/media_types/pdf/processing.py,
+   unoconv_supported.
+
+All executables must be on your execution path.
+
+To install this on Fedora:
+
+.. code-block:: bash
+
+    sudo yum install -y poppler-utils unoconv libreoffice-headless
+
+Note: You can leave out unoconv and libreoffice-headless if you want only pdf
+support. This will result in a much smaller list of dependencies.
+
+pdf.js relies on git submodules, so be sure you have fetched them:
+
+.. code-block:: bash
+
+    git submodule init
+    git submodule update
+
+This feature has been tested on Fedora with:
+ poppler-utils-0.20.2-9.fc18.x86_64
+ unoconv-0.5-2.fc18.noarch
+ libreoffice-headless-3.6.5.2-8.fc18.x86_64
+
+It may work on some earlier versions, but that is not guaranteed.
+
+Add ``mediagoblin.media_types.pdf`` to the ``media_types`` list in your
+``mediagoblin_local.ini`` and restart MediaGoblin. 
+
+Run
+
+.. code-block:: bash
+
+    ./bin/gmg dbupdate
+
+
diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst
new file mode 100644
index 00000000..baca381d
--- /dev/null
+++ b/docs/source/siteadmin/plugins.rst
@@ -0,0 +1,177 @@
+=========
+ 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-licenses" (which allows you to customize the licenses you
+offer for your media), we would do::
+
+    pip install mediagoblin-licenses
+
+.. 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. Also make sure, you use e.g. pip-2.7 if your default
+   python (and thus pip) is python 3 (e.g. in Ubuntu).
+
+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-licenses" plugin has the Python
+package path ``mediagoblin_licenses``, then you would add ``mediagoblin_licenses`` to
+the ``plugins`` section as a subsection::
+
+    [plugins]
+
+    [[mediagoblin_licenses]]
+    license_01=abbrev1, name1, http://url1
+    license_02=abbrev2, name1, http://url2
+
+
+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.flatpagesfile`` and you would add
+that to your ``.ini`` file like this::
+
+    [plugins]
+
+    [[mediagoblin.plugins.flatpagesfile]]
+    # configuration for flatpagesfile plugin here!
+    about-view = '/about', about.html
+    terms-view = '/terms', terms.html
+
+(Want to know more about the flatpagesfile plugin?  See
+:ref:`flatpagesfile-chapter`)
+
+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-licenses
+
+.. 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.
+
+
+Troubleshooting plugins
+=======================
+
+Sometimes plugins just don't work right. When you're having problems
+with plugins, think about the following:
+
+1. Check the log files.
+
+   Some plugins will log errors to the log files and you can use that
+   to diagnose the problem.
+
+2. Try running MediaGoblin without that plugin.
+
+   It's easy to disable a plugin from MediaGoblin. Add a ``-`` to the
+   name in your config file.
+
+   For example, change::
+
+       [[mediagoblin.plugins.flatpagesfile]]
+
+   to::
+
+       [[-mediagoblin.plugins.flatpagesfile]]
+
+   That'll prevent the ``mediagoblin.plugins.flatpagesfile`` plugin from
+   loading.
+
+3. If it's a core plugin that comes with MediaGoblin, ask us for help!
+
+   If it's a plugin you got from somewhere else, ask them for help!
diff --git a/docs/source/siteadmin/production-deployments.rst b/docs/source/siteadmin/production-deployments.rst
new file mode 100644
index 00000000..839d3ce5
--- /dev/null
+++ b/docs/source/siteadmin/production-deployments.rst
@@ -0,0 +1,133 @@
+.. 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 MediaGoblin WSGI application instance you get 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:
+
+.. code-block:: bash
+
+    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:
+
+.. code-block:: bash
+
+    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
+---------------
+
+MediaGoblin uses `Celery`_ to handle heavy and long-running tasks. Celery can
+be launched in two ways:
+
+1.  Embedded in the MediaGoblin WSGI application [#f-mediagoblin-wsgi-app]_.
+    This is the way ``./lazyserver.sh`` does it for you. It's simple as you
+    only have to run one process. The only bad thing with this is that the
+    heavy and long-running tasks will run *in* the webserver, keeping the user
+    waiting each time some heavy lifting is needed as in for example processing
+    a video. This could lead to problems as an aborted connection will halt any
+    processing and since most front-end web servers *will* terminate your
+    connection if it doesn't get any response from the MediaGoblin WSGI
+    application in a while.
+
+2.  As a separate process communicating with the MediaGoblin WSGI application
+    via a `broker`_. This offloads the heavy lifting from the MediaGoblin WSGI
+    application and users will be able to continue to browse the site while the
+    media is being processed in the background.
+
+.. _`broker`: http://docs.celeryproject.org/en/latest/getting-started/brokers/
+.. _`celery`: http://www.celeryproject.org/
+
+
+.. [#f-mediagoblin-wsgi-app] The MediaGoblin WSGI application is the part that
+    of MediaGoblin that processes HTTP requests.
+
+To launch Celery separately from the MediaGoblin WSGI application:
+
+1.  Make sure that the ``CELERY_ALWAYS_EAGER`` environment variable is unset or
+    set to ``false`` when launching the MediaGoblin WSGI application.
+2.  Start the ``celeryd`` main process with
+
+    .. code-block:: bash
+
+        CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd
+
+.. _sentry:
+
+Set up sentry to monitor exceptions
+-----------------------------------
+
+We have a plugin for `raven`_ integration, see the ":doc:`/plugindocs/raven`"
+documentation.
+
+.. _`raven`: http://raven.readthedocs.org
+
+
+.. _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.
+
+These are scripts provided by the MediaGoblin community: 
+
+Debian
+  * `GNU MediaGoblin init scripts
+    <https://github.com/joar/mediagoblin-init-scripts>`_
+    by `Joar Wandborg <http://wandborg.se>`_
+
+Arch Linux
+  * `MediaGoblin - ArchLinux rc.d scripts
+    <http://whird.jpope.org/2012/04/14/mediagoblin-archlinux-rcd-scripts>`_
+    by `Jeremy Pope <http://jpope.org/>`_
+  * `Mediagoblin init script on Archlinux
+    <http://chimo.chromic.org/2012/03/01/mediagoblin-init-script-on-archlinux/>`_
+    by `Chimo <http://chimo.chromic.org/>`_
+
+.. 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..7b6d8353
--- /dev/null
+++ b/docs/source/siteadmin/relnotes.rst
@@ -0,0 +1,300 @@
+.. 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:
+
+=============
+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.4.0
+=====
+
+**Do this to upgrade**
+1. Make sure to run ``bin/gmg dbupdate`` after upgrading.
+2. See "For Theme authors" if you have a custom theme.
+3. Note that ``./bin/gmg theme assetlink`` is now just
+   ``./bin/gmg assetlink`` and covers both plugins and assets.
+   Keep on reading to hear more about new plugin features.
+4. If you want to take advantage of new plugins that have statically
+   served assets, you are going to need to add the new "plugin_static"
+   section to your nginx config.  Basically the following for nginx::
+
+     # Plugin static files (usually symlinked in)
+     location /plugin_static/ {
+        alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/;
+     }
+
+   Similarly, if you've got a modified paste config, you may want to
+   borrow the app:plugin_static section from the default paste.ini
+   file.
+5. We now use itsdangerous for sessions; if you had any references to
+   beaker in your paste config you can remove them.  Again, see the
+   default paste.ini config
+
+**For theme authors**
+
+If you have your own theme or you have any "user modified templates",
+please note the following:
+
+* mediagoblin/bits/ files above-content.html, body-end.html,
+  body-start.html now are renamed... they have underscores instead of
+  dashes in the filenames now :)
+* There's a new file: ``mediagoblin/bits/frontpage_welcome.html``.
+  You can easily customize this to give a welcome page appropriate to
+  your site.
+
+
+**New features**
+* PDF media type!
+* Improved plugin system.  More flexible, better documented, with a
+  new plugin authoring section of the docs.
+* itsdangerous based sessions.  No more beaker!
+* New, experimental Piwigo-based API.  This means you should be able
+  to use MediaGoblin with something like Shotwell.  (Again, a word of
+  caution: this is *very experimental*!)
+* Human readable timestamps, and the option to display the original
+  date of an image when available (available as the
+  "original_date_visible" variable)
+* Moved unit testing system from nosetests to py.test so we can better
+  handle issues with sqlalchemy exploding with different database
+  configurations.  Long story :)
+* You can now disable the ability to post comments.
+* Tags now can be up to length 255 characters by default.
+
+
+0.3.3
+=====
+
+**Do this to upgrade**
+
+1. Make sure to run ``bin/gmg dbupdate`` after upgrading.
+2. OpenStreetMap is now a plugin, so if you want to use it, add the
+   following to your config file:
+
+   .. code-block:: ini
+
+      [plugins]
+      [[mediagoblin.plugins.geolocation]]
+
+If you have your own theme, you may need to make some adjustments to
+it as some theme related things may have changed in this release.  If
+you run into problems, don't hesitate to
+`contact us <http://mediagoblin.org/pages/join.html>`_
+(IRC is often best).
+
+**New features**
+
+* New dropdown menu for accessing various features.
+
+* Significantly improved URL generation.  Now mediagoblin won't give
+  up on making a slug if it looks like there will be a duplicate;
+  it'll try extra hard to generate a meaningful one instead.
+
+  Similarly, linking to an id no longer can possibly conflict with
+  linking to a slug; /u/username/m/id:35/ is the kind of reference we
+  now use to linking to entries with ids.  However, old links with
+  entries that linked to ids should work just fine with our migration.
+  The only urls that might break in this release are ones using colons
+  or equal signs.
+
+* New template hooks for plugin authoring.
+
+* As a demonstration of new template hooks for plugin authoring,
+  openstreetmap support now moved to a plugin!
+
+* Method to add media to collections switched from icon of paperclip
+  to button with "add to collection" text.
+
+* Bug where videos often failed to produce a proper thumbnail fixed!
+
+* Copying around files in MediaGoblin now much more efficient, doesn't
+  waste gobs of memory.
+
+* Video transcoding now optional for videos that meet certain
+  criteria.  By default, MediaGoblin will not transcode webm videos
+  that are smaller in resolution than the MediaGoblin defaults, and
+  MediaGoblin can also be configured to allow theora files to not be
+  transcoded as well.
+
+* Per-user license preference option; always want your uploads to be
+  BY-SA and tired of changing that field?  You can now set your
+  license preference in your user settings.
+
+* Video player now responsive; better for mobile!
+
+* You can now delete your account from the user preferences page if
+  you so wish.
+
+**Other changes**
+
+* Plugin writers: Internal restructuring led to mediagoblin.db.sql* be
+  mediagoblin.db.* starting from 0.3.3
+
+* Dependency list has been reduced not requiring the "webob" package anymore.
+
+* And many small fixes/improvements, too numerous to list!
+
+
+0.3.2
+=====
+
+This will be the last release that is capable of converting from an earlier
+MongoDB-based MediaGoblin instance to the newer SQL-based system.
+
+**Do this to upgrade**
+
+    # directory of your mediagoblin install
+    cd /srv/mediagoblin.example.org
+
+    # copy source for this release
+    git fetch
+    git checkout tags/v0.3.2
+
+    # perform any needed database updates
+    bin/gmg dbupdate
+    
+    # restart your servers however you do that, e.g.,
+    sudo service mediagoblin-paster restart
+    sudo service mediagoblin-celeryd restart
+
+
+**New features**
+
+* **3d model support!**
+
+  You can now upload STL and OBJ files and display them in
+  MediaGoblin.  Requires a recent-ish Blender; for details see:
+  :ref:`deploying-chapter`
+
+* **trim_whitespace**
+
+  We bundle the optional plugin trim_whitespace which reduces the size
+  of the delivered html output by reducing redundant whitespace.
+
+  See :ref:`core-plugin-section` for plugin documentation
+
+* **A new API!**
+
+  It isn't well documented yet but we do have an API.  There is an
+  `android application in progress <https://gitorious.org/mediagoblin/mediagoblin-android>`_
+  which makes use of it, and there are some demo applications between
+  `automgtic <https://github.com/jwandborg/automgtic>`_, an
+  automatic media uploader for your desktop
+  and `OMGMG <https://github.com/jwandborg/omgmg>`_, an example of
+  a web application hooking up to the API.
+
+  This is a plugin, so you have to enable it in your mediagoblin
+  config file by adding a section under [plugins] like::
+
+    [plugins]
+    [[mediagoblin.plugins.api]]
+
+  Note that the API works but is not nailed down... the way it is
+  called may change in future releases.
+
+* **OAuth login support**
+
+  For applications that use OAuth to connect to the API.
+
+  This is a plugin, so you have to enable it in your mediagoblin
+  config file by adding a section under [plugins] like::
+
+    [plugins]
+    [[mediagoblin.plugins.oauth]]
+
+* **Collections**
+
+  We now have user-curated collections support.  These are arbitrary
+  galleries that are customizable by users.  You can add media to
+  these by clicking on the paperclip icon when logged in and looking
+  at a media entry.
+
+* **OpenStreetMap licensing display improvements**
+
+  More accurate display of OSM licensing, and less disruptive: you
+  click to "expand" the display of said licensing.
+
+  Geolocation is also now on by default.
+
+* **Miscelaneous visual improvements**
+
+  We've made a number of small visual improvements including newer and
+  nicer looking thumbnails and improved checkbox placement.
+
+
+
+0.3.1
+=====
+
+**Do this to upgrade**
+
+1. Make sure to run ``bin/gmg dbuptdate`` after upgrading.
+
+2. If you set up your server config with an older version of
+   mediagoblin and the mediagoblin docs, it's possible you don't
+   have the "theme static files" alias, so double check to make
+   sure that section is there if you are having problems.
+
+
+
+**New features**
+
+* **theming support**
+
+  MediaGoblin now also includes theming support, which you can
+  read about in the section :ref:`theming-chapter`.
+
+* **flatpages**
+
+  MediaGoblin has a flatpages plugin allowing you to add pages that
+  are aren't media-related like "About this site...", "Terms of
+  service...", etc.
+
+  See :ref:`core-plugin-section` for plugin documentation
+
+
+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..11ae3875
--- /dev/null
+++ b/docs/source/siteadmin/theming.rst
@@ -0,0 +1,281 @@
+.. 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 try to provide a nice theme for MediaGoblin by default, but of
+course, you might want something different!  Maybe you want something
+more light and colorful, or maybe you want something specifically
+tailored to your organization.  Have no fear---MediaGoblin has theming
+support!  This guide should walk you through installing and making
+themes.
+
+
+Installing a theme
+==================
+
+.. _theming-installing-section:
+
+Installing the archive
+----------------------
+
+Say you have a theme archive such as ``goblincities.tar.gz`` and you
+want to install this theme!  Don't worry, it's fairly painless.
+
+1. ``cd ./user_dev/themes/``
+
+2. Move the theme archive into this directory
+
+3. ``tar -xzvf <tar-archive>``
+
+4. Open your configuration file (probably named
+   ``mediagoblin_local.ini``) and set the theme name::
+
+       [mediagoblin]
+       # ...
+       theme = goblincities
+
+5. Link the assets so that they can be served by your web server::
+
+       $ ./bin/gmg assetlink
+
+.. Note::
+
+   If you ever change the current theme in your config file, you
+   should re-run the above command!
+
+(In the near future this should be even easier ;))
+
+.. In the future, this might look more like:
+.. Installing a theme in MediaGoblin is fairly easy!  Assuming you
+.. already have a theme package, just do this::
+..
+..     $ ./bin/gmg theme install --fullsetup goblincities.tar.gz
+..
+.. This would install the theme, set it as current, and symlink its
+.. assets.
+
+
+Set up your webserver to serve theme assets
+-------------------------------------------
+
+If you followed the nginx setup example in :ref:`webserver-config` you
+should already have theme asset setup.  However, if you set up your
+server config with an older version of mediagoblin and the mediagoblin
+docs, it's possible you don't have the "theme static files" alias, so
+double check to make sure that section is there if you are having
+problems.
+
+If you are simply using this for local development and serving the
+whole thing via paste/lazyserver, assuming you don't have a
+paste_local.ini, the asset serving should be done for you.
+
+
+Configuring where things go
+---------------------------
+
+By default, MediaGoblin's install directory for themes is
+``./user_dev/themes/`` (relative to the MediaGoblin checkout or base
+config file.)  However, you can change this location easily with the
+``theme_install_dir`` setting in the ``[mediagoblin]`` section.
+
+For example::
+
+    [mediagoblin]
+    # ... other parameters go here ...
+    theme_install_dir = /path/to/themes/
+
+Other variables you may consider setting:
+
+`theme_web_path`
+    When theme-specific assets are specified, this is where MediaGoblin
+    will set the urls.  By default this is ``"/theme_static/"`` so in
+    the case that your theme was trying to access its file 
+    ``"images/shiny_button.png"`` MediaGoblin would link
+    to ``/theme_static/images/shiny_button.png``.
+
+`theme_linked_assets_dir`
+    Your web server needs to serve the theme files out of some directory,
+    and MediaGoblin will symlink the current theme's assets here.  See
+    the "Link the assets" step in :ref:`theming-installing-section`.
+
+
+Making a theme
+==============
+
+Okay, so a theme layout is pretty simple.  Let's assume we're making a
+theme for an instance about hedgehogs!  We'll call this the
+"hedgehogified" theme.
+
+Change to where your ``theme_install_dir`` is set to (by default,
+``./user_dev/themes/`` ... make those directories or otherwise adjust
+if necessary)::
+
+    hedgehogified/
+    |- theme.cfg                # configuration file for this theme
+    |- templates/               # override templates
+    |  '- mediagoblin/
+    |     |- base.html          # overriding mediagoblin/base.html
+    |     '- root.html          # overriding mediagoblin/root.html
+    '- assets/
+    |  '- images/
+    |  |  |- im_a_hedgehog.png  # hedgehog-containing image used by theme
+    |  |  '- custom_logo.png    # your theme's custom logo
+    |  '- css/
+    |     '- hedgehog.css       # your site's hedgehog-specific css
+    |- README.txt               # Optionally, a readme file (not required)
+    |- AGPLv3.txt               # AGPL license file for your theme. (good practice)
+    '- CC0_1.0.txt              # CC0 1.0 legalcode for the assets [if appropriate!]
+
+
+The top level directory of your theme should be the symbolic name for
+your theme.  This is the name that users will use to refer to activate
+your theme.
+
+.. Note::
+
+   It's important to note that templates based on MediaGoblin's code
+   should be released as AGPLv3 (or later), like MediaGoblin's code
+   itself.  However, all the rest of your assets are up to you.  In this
+   case, we are waiving our copyright for images and CSS into the public
+   domain via CC0 (as MediaGoblin does) but do what's appropriate to you.
+
+
+The config file
+===============
+
+The config file is not presently strictly required, though it is nice to have.
+Only a few things need to go in here::
+
+    [theme]
+    name = Hedgehog-ification
+    description = For hedgehog lovers ONLY
+    licensing = AGPLv3 or later templates; assets (images/css) waived under CC0 1.0
+
+The name and description fields here are to give users an idea of what
+your theme is about.  For the moment, we don't have any listing
+directories or admin interface, so this probably isn't useful, but
+feel free to set it in anticipation of a more glorious future.
+
+Licensing field is likewise a textual description of the stuff here;
+it's recommended that you preserve the "AGPLv3 or later templates" and
+specify whatever is appropriate to your assets.
+
+
+Templates
+---------
+
+Your template directory is where you can put any override and custom
+templates for MediaGoblin.
+
+These follow the general MediaGoblin theming layout, which means that
+the MediaGoblin core templates are all kept under the ``./mediagoblin/``
+prefix directory.
+
+You can copy files right out of MediaGoblin core and modify them in
+this matter if you wish.
+
+To fit with best licensing form, you should either preserve the
+MediaGoblin copyright header borrowing from a MediaGoblin template, or
+you may include one like the following::
+
+    {#
+    # [YOUR THEME], a MediaGoblin theme
+    # Copyright (C) [YEAR] [YOUR NAME]
+    #
+    # This program is free software: you can redistribute it and/or modify
+    # it under the terms of the GNU Affero General Public License as published by
+    # the Free Software Foundation, either version 3 of the License, or
+    # (at your option) any later version.
+    #
+    # This program is distributed in the hope that it will be useful,
+    # but WITHOUT ANY WARRANTY; without even the implied warranty of
+    # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    # GNU Affero General Public License for more details.
+    #
+    # You should have received a copy of the GNU Affero General Public License
+    # along with this program.  If not, see <http://www.gnu.org/licenses/>.
+    #}
+
+
+Assets
+------
+
+Put any files, such as images, CSS, etc, that are specific to your
+theme in here.
+
+You can reference these in your templates like so::
+
+    <img src="{{ request.staticdirect('/images/im_a_shark.png', 'theme') }}" />
+
+This will tell MediaGoblin to reference this image from the current theme.
+
+
+Licensing file(s)
+-----------------
+
+You should include AGPLv3.txt with your theme as this is required for
+the assets.  You can copy this from ``mediagoblin/licenses/``.
+
+In the above example, we also use CC0 to waive our copyrights to
+images and css, so we also included CC0_1.0.txt
+
+
+A README.txt file
+-----------------
+
+A README file is not strictly required, but probably a good idea.  You
+can put whatever in here, but restating the license choice clearly is
+probably a good idea.
+
+
+Simple theming by adding CSS
+----------------------------
+
+Many themes won't require anything other than the ability to override
+some of MediaGoblin's core css.  Thankfully, doing so is easy if you
+combine the above steps!
+
+In your theme, do the following (make sure you make the necessary
+directories and cd to your theme's directory first)::
+
+    $ cp /path/to/mediagoblin/mediagoblin/templates/mediagoblin/extra_head.html templates/mediagoblin/
+
+Great, now open that file and add something like this at the end::
+
+    <link rel="stylesheet" type="text/css"
+          href="{{ request.staticdirect('/css/theme.css', 'theme') }}"/>
+
+You can name the css file whatever you like.  Now make the directory
+for ``assets/css/`` and add the file ``assets/css/theme.css``.
+
+You can now put custom CSS files in here and any CSS you add will
+override default MediaGoblin CSS.
+
+
+Packaging it up!
+----------------
+
+Packaging a theme is really easy.  It's just a matter of making an archive!
+
+Change to the installed themes directory and run the following::
+
+    tar -cvfz yourtheme.tar.gz yourtheme
+
+Where "yourtheme" is replaced with your theme name.
+
+That's it!