From 2530ef7a1f682dcd5c4386d6b66b1fb71e8cc554 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Wed, 23 May 2012 20:21:03 -0400 Subject: Split docs into siteadmin and pluginwriter guides * create initial bits for plugin writer's guide * move siteadmin stuff to site administrator's guide * rework index.rst to support multiple guides * tweak some text * move files into subdirectories I verified that this still works with html and texinfo build targets. There's still a lot of work to do, but this is a good start. --- docs/source/siteadmin/about.rst | 101 +++++++ docs/source/siteadmin/codebase.rst | 160 ++++++++++++ docs/source/siteadmin/configuration.rst | 129 +++++++++ docs/source/siteadmin/deploying.rst | 320 +++++++++++++++++++++++ docs/source/siteadmin/foreword.rst | 48 ++++ docs/source/siteadmin/help.rst | 29 ++ docs/source/siteadmin/media-types.rst | 76 ++++++ docs/source/siteadmin/plugins.rst | 137 ++++++++++ docs/source/siteadmin/production-deployments.rst | 94 +++++++ docs/source/siteadmin/relnotes.rst | 52 ++++ docs/source/siteadmin/theming.rst | 21 ++ 11 files changed, 1167 insertions(+) create mode 100644 docs/source/siteadmin/about.rst create mode 100644 docs/source/siteadmin/codebase.rst create mode 100644 docs/source/siteadmin/configuration.rst create mode 100644 docs/source/siteadmin/deploying.rst create mode 100644 docs/source/siteadmin/foreword.rst create mode 100644 docs/source/siteadmin/help.rst create mode 100644 docs/source/siteadmin/media-types.rst create mode 100644 docs/source/siteadmin/plugins.rst create mode 100644 docs/source/siteadmin/production-deployments.rst create mode 100644 docs/source/siteadmin/relnotes.rst create mode 100644 docs/source/siteadmin/theming.rst (limited to 'docs/source/siteadmin') 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 + . + +======================= + 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 `_ 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 + . + +.. _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 `_ + for where we hang out. + +For more information on how to get started hacking on GNU MediaGoblin, +see `the wiki `_. + + +Software Stack +============== + +* Project infrastructure + + * `Python `_: the language we're using to write + this + + * `Nose `_: + for unit tests + + * `virtualenv `_: 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 `_: SQL ORM and database + interaction library for Python. Currently we support sqlite and + postgress as backends. + +* Web application + + * `Paste Deploy `_ and + `Paste Script `_: we'll use this for + configuring and launching the application + + * `WebOb `_: nice abstraction layer + from HTTP requests, responses and WSGI bits + + * `Routes `_: for URL routing + + * `Beaker `_: for handling sessions and + caching + + * `Jinja2 `_: the templating engine + + * `WTForms `_: for handling, + validation, and abstraction from HTML forms + + * `Celery `_: for task queuing (resizing + images, encoding video, ...) + + * `Babel `_: Used to extract and compile + translations. + + * `Markdown (for python) `_: + implementation of `Markdown `_ + text-to-html tool to make it easy for people to write richtext + comments, descriptions, and etc. + + * `lxml `_: nice xml and html processing for + python. + +* Media processing libraries + + * `Python Imaging Library `_: + used to resize and otherwise convert images for display. + + * `GStreamer `_: (Optional, for + video hosting sites only) Used to transcode video, and in the + future, probably audio too. + + * `chardet `_: (Optional, for + ascii art hosting sites only) Used to make ascii art thumbnails. + +* Front end + + * `JQuery `_: 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 + . + +.. _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 + `_ / `paste 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 + . + +.. _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 `_ instead. + +Prepare System +-------------- + +Dependencies +~~~~~~~~~~~~ + +MediaGoblin has the following core dependencies: + +- Python 2.6 or 2.7 +- `python-lxml `_ +- `git `_ +- `SQLite `_/`PostgreSQL `_ +- `Python Imaging Library `_ (PIL) +- `virtualenv `_ + +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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 +. 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 + . + +======== +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 + . + +================================== + 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 + . + +.. _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 `_ +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 +`_, then you can install the plugin with pip:: + + pip install + +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 + +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 + . + +========================================= +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 ` 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 + . + +============= +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 + . + +.. _theming-chapter: + +===================== + Theming MediaGoblin +===================== + +We haven't implemented the necessary scaffolding to allow for theming +yet. Thus, this chapter is a stub. -- cgit v1.2.3 From 84336a46b1b95aab9733a9ff0ac3c03303a326c5 Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Mon, 28 May 2012 01:08:38 +0200 Subject: Added links to community-provied init scripts --- docs/source/siteadmin/production-deployments.rst | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/production-deployments.rst b/docs/source/siteadmin/production-deployments.rst index 1e6631db..356fab7f 100644 --- a/docs/source/siteadmin/production-deployments.rst +++ b/docs/source/siteadmin/production-deployments.rst @@ -85,8 +85,22 @@ 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. +distribution/operating system. + +These are scripts provided by the MediaGoblin community: + +Debian + * `GNU MediaGoblin init scripts + `_ + by `Joar Wandborg `_ + +Arch Linux + * `MediaGoblin - ArchLinux rc.d scripts + `_ + by `Jeremy Pope `_ + * `Mediagoblin init script on Archlinux + `_ + by `Chimo `_ .. TODO insert init script here .. TODO are additional concerns ? -- cgit v1.2.3 From 0e60e7e81b58f2ef8ca4bd571bb9544e41e573c8 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Sat, 2 Jun 2012 22:03:03 -0400 Subject: Add link to wiki on front page; fix about Adds a summary and a link to the wiki for contributors to the front page. The "what is mediagoblin" section in the about chapter talkd about what it was, but it was buried--this slightly unburies it. --- docs/source/siteadmin/about.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/about.rst b/docs/source/siteadmin/about.rst index 95647abb..f9602397 100644 --- a/docs/source/siteadmin/about.rst +++ b/docs/source/siteadmin/about.rst @@ -36,10 +36,11 @@ freedom look like on the participatory web?" Their answer, the 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 +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. -- cgit v1.2.3 From d34757dc830903fc55898ca7ea923f7a2ea6e646 Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Fri, 6 Jul 2012 22:51:49 +0200 Subject: Updated the media types documentation, added steps for audio - Added chapter about media type negotiation. - Added instructions on how to install dependencies for the audio media type. - Moved part about how to enable media types in your config to a single place at the top of the document named "Enable Media Types". - Renamed the "Enable Media Types" page to "Media Types". --- docs/source/siteadmin/media-types.rst | 73 +++++++++++++++++++++++++++++------ 1 file changed, 62 insertions(+), 11 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index 1cf7f30c..d062da95 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -14,16 +14,49 @@ .. _media-types-chapter: ==================== -Enabling Media Types +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. +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 + +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 ===== @@ -34,14 +67,6 @@ 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. @@ -54,6 +79,32 @@ transcode them. ":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:: + + sudo apt-get install libsndfile1-dev + +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. You should now be able to +upload and listen to audio files! + + Ascii art ========= -- cgit v1.2.3 From e6aaaa96193b20d805c82214debd5a2cd8855efd Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sat, 14 Jul 2012 15:54:14 -0500 Subject: Fleshing out theming documentation; wrote out "structure of things" section --- docs/source/siteadmin/theming.rst | 94 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 92 insertions(+), 2 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst index 7584b688..27f39e97 100644 --- a/docs/source/siteadmin/theming.rst +++ b/docs/source/siteadmin/theming.rst @@ -17,5 +17,95 @@ Theming MediaGoblin ===================== -We haven't implemented the necessary scaffolding to allow for theming -yet. Thus, this chapter is a stub. +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. + + +Making a theme +-------------- + +The structure of things +======================= + +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. + + 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.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. + +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 +~~~~~~~~~~~~~~~ + +Only a few things need to go in here. + + [theme] + name = hedgehogified + description = For hedgehog lovers ONLY + licensing = AGPLv3 or later templates; assets (images/css) waived under CC0 1.0 + + +Templates +~~~~~~~~~ + +Templates + +Licensing file(s) +~~~~~~~~~~~~~~~~~ + + + + +A README.txt file +~~~~~~~~~~~~~~~~~ + +A readme file is not strictly required, but probably a good idea. + + +Referring to custom assets in your themes +========================================= + + + + +Installing a theme +------------------ + +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 installs, archives, and + + +Making a themes +--------------- + + -- cgit v1.2.3 From 04b24107fbe197a8bd278b908651cea14911dff4 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sat, 14 Jul 2012 20:22:25 -0500 Subject: Mostly good theming documentation! --- docs/source/siteadmin/theming.rst | 173 +++++++++++++++++++++++++++++++++----- 1 file changed, 150 insertions(+), 23 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst index 27f39e97..63beaf3c 100644 --- a/docs/source/siteadmin/theming.rst +++ b/docs/source/siteadmin/theming.rst @@ -24,16 +24,92 @@ tailored to your organization. Have no fear, MediaGoblin has theming support! This guide should walk you through installing and making themes. +Installing a theme +------------------ + +Installing the archive +====================== + +Say you have a theme archive such as goblincities.tar.gz. You want to +install this theme! Don't worry, it's fairly painless. + +Simply cd to the "install directory" for themes (by default, +./user_dev/themes/ relative to the mediagoblin install directory... to +configure these things, see the next section), move the archive there, +and decompress. + + tar xvfz goblincities.tar.gz + +Next, open up your mediagoblin configuration file (probably +mediagoblin_local.ini) and set the theme name: + + [mediagoblin] + # ... + theme = goblincities + +Finally, "link the assets" so that they can be served by your web +server. + + ./bin/gmg theme 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 +=========================================== + +Section to be written, ask on #mediagoblin in irc.freenode.net in the +meanwhile ;) + +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. In your +mediagoblin config file, under the section [mediagoblin] set the +following parameter: + + [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 "Linking assets" in the theme + install section) + + Making a theme -------------- -The structure of things -======================= - 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 if necessary and +otherwise adjust if necessary) + hedgehogified/ |- theme.cfg # configuration file for this theme |- templates/ # override templates @@ -48,7 +124,7 @@ theme for an instance about hedgehogs! We'll call this the | '- 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.txt # CC0 1.0 legalcode for the assets [if appropriate!] + '- 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 @@ -61,51 +137,102 @@ 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 = hedgehogified + 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 -~~~~~~~~~ Templates +========= -Licensing file(s) -~~~~~~~~~~~~~~~~~ +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 if a new file: -A README.txt file -~~~~~~~~~~~~~~~~~ + {# + # [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 . + #} -A readme file is not strictly required, but probably a good idea. +Assets +======= -Referring to custom assets in your themes -========================================= +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: + +This will tell MediaGoblin to reference this image from the current theme. -Installing a theme ------------------- -Installing a theme in MediaGoblin is fairly easy! Assuming you -already have a theme package, just do this: +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. + - $ ./bin/gmg theme install --fullsetup goblincities.tar.gz +Packaging it up! +================ -This installs, archives, and +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: -Making a themes ---------------- + tar cvfz yourtheme.tar.gz yourtheme +Where "yourtheme" is replaced with your theme name. +That's it! -- cgit v1.2.3 From 62157a898f60fab7c82eb76b2969354f9f02390d Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sat, 14 Jul 2012 22:58:42 -0500 Subject: Added a section describing how to do theming via simple CSS stuff! --- docs/source/siteadmin/theming.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst index 63beaf3c..086838bc 100644 --- a/docs/source/siteadmin/theming.rst +++ b/docs/source/siteadmin/theming.rst @@ -224,6 +224,30 @@ 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: + + + +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! ================ -- cgit v1.2.3 From 8464bcc3e86e223db0739101c0b5d914eea225af Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Mon, 16 Jul 2012 17:06:57 -0400 Subject: Fix themeing docs This fixes a bunch of formatting issues in the themeing docs and makes them easier to read. --- docs/source/siteadmin/theming.rst | 151 ++++++++++++++++++++------------------ 1 file changed, 78 insertions(+), 73 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst index 086838bc..74bc80dc 100644 --- a/docs/source/siteadmin/theming.rst +++ b/docs/source/siteadmin/theming.rst @@ -25,32 +25,32 @@ support! This guide should walk you through installing and making themes. Installing a theme ------------------- +================== Installing the archive -====================== +---------------------- Say you have a theme archive such as goblincities.tar.gz. You want to install this theme! Don't worry, it's fairly painless. Simply cd to the "install directory" for themes (by default, -./user_dev/themes/ relative to the mediagoblin install directory... to +``./user_dev/themes/`` relative to the mediagoblin install directory... to configure these things, see the next section), move the archive there, -and decompress. +and decompress:: - tar xvfz goblincities.tar.gz + $ tar xvfz goblincities.tar.gz Next, open up your mediagoblin configuration file (probably -mediagoblin_local.ini) and set the theme name: +``mediagoblin_local.ini``) and set the theme name:: - [mediagoblin] - # ... - theme = goblincities + [mediagoblin] + # ... + theme = goblincities Finally, "link the assets" so that they can be served by your web -server. +server:: - ./bin/gmg theme assetlink + $ ./bin/gmg theme assetlink Note, if you ever change the current theme in your config file, you should re-run the above command! @@ -59,56 +59,59 @@ should re-run the above command! .. 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 - +.. 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 -=========================================== +------------------------------------------- Section to be written, ask on #mediagoblin in irc.freenode.net in the meanwhile ;) + 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. In your mediagoblin config file, under the section [mediagoblin] set the -following parameter: +following parameter:: - [mediagoblin] - # ... other parameters go here ... - theme_install_dir = /path/to/themes/ + [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 "Linking assets" in the theme - install section) +`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 + "Linking assets" in the theme install 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 if necessary and -otherwise adjust if necessary) +``./user_dev/themes/`` ... make those directories if necessary and +otherwise adjust if necessary):: hedgehogified/ |- theme.cfg # configuration file for this theme @@ -126,6 +129,7 @@ otherwise adjust if necessary) |- 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. @@ -136,16 +140,17 @@ 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. +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 + [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 @@ -158,13 +163,13 @@ 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/ +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 @@ -172,34 +177,34 @@ 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 if a new file: - - {# - # [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 . - #} +you may include one like the following if a new file:: + + {# + # [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 . + #} 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: +You can reference these in your templates like so:: @@ -207,17 +212,17 @@ 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/ +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 @@ -225,21 +230,21 @@ 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): +directories and cd to your theme's directory first):: - $ cp /path/to/mediagoblin/mediagoblin/templates/mediagoblin/extra_head.html templates/mediagoblin/ + $ 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: +Great, now open that file and add something like this at the end:: - + You can name the css file whatever you like. Now make the directory for assets/css/ and add the file assets/css/theme.css @@ -249,13 +254,13 @@ 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: +Change to the installed themes directory and run the following:: - tar cvfz yourtheme.tar.gz yourtheme + tar cvfz yourtheme.tar.gz yourtheme Where "yourtheme" is replaced with your theme name. -- cgit v1.2.3 From 05d8f314c639f30a699c63e3d4f8feae9a5ba60b Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Tue, 17 Jul 2012 21:14:45 -0400 Subject: [Issue 466] Implement e-z plugin disabling --- docs/source/siteadmin/plugins.rst | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst index 41f2970f..f5a78da7 100644 --- a/docs/source/siteadmin/plugins.rst +++ b/docs/source/siteadmin/plugins.rst @@ -135,3 +135,35 @@ For plugins that you install with pip, you can upgrade them with pip:: pip install -U 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.flatpages]] + + to:: + + [[-mediagoblin.plugins.flatpages]] + + That'll prevent the ``mediagoblin.plugins.flatpages`` 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! -- cgit v1.2.3 From 4d1761d22fd9c6f2e0ee533236c47bb1ba51f507 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Thu, 26 Jul 2012 21:33:25 -0400 Subject: Tweak theming docs I did a pass on language and more reST formatting. This is a little cleaner, though there are a couple of parts that feel like they could use some work. --- docs/source/siteadmin/theming.rst | 104 ++++++++++++++++++++------------------ 1 file changed, 55 insertions(+), 49 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst index 74bc80dc..b22de727 100644 --- a/docs/source/siteadmin/theming.rst +++ b/docs/source/siteadmin/theming.rst @@ -17,43 +17,46 @@ Theming MediaGoblin ===================== -We try to provide a nice theme for MediaGoblin by default. But of +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. +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. You want to -install this theme! Don't worry, it's fairly painless. +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. -Simply cd to the "install directory" for themes (by default, -``./user_dev/themes/`` relative to the mediagoblin install directory... to -configure these things, see the next section), move the archive there, -and decompress:: +1. ``cd ./user_dev/themes/`` - $ tar xvfz goblincities.tar.gz +2. Move the theme archive into this directory -Next, open up your mediagoblin configuration file (probably -``mediagoblin_local.ini``) and set the theme name:: +3. ``tar -xzvf `` - [mediagoblin] - # ... - theme = goblincities +4. Open your configuration file (probably named + ``mediagoblin_local.ini``) and set the theme name:: + + [mediagoblin] + # ... + theme = goblincities -Finally, "link the assets" so that they can be served by your web -server:: +5. Link the assets so that they can be served by your web server:: - $ ./bin/gmg theme assetlink + $ ./bin/gmg theme assetlink -Note, if you ever change the current theme in your config file, you -should re-run the above command! +.. 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 ;)) @@ -70,7 +73,7 @@ should re-run the above command! Set up your webserver to serve theme assets ------------------------------------------- -Section to be written, ask on #mediagoblin in irc.freenode.net in the +FIXME - To be written. Ask on #mediagoblin in irc.freenode.net in the meanwhile ;) @@ -78,10 +81,11 @@ 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. In your -mediagoblin config file, under the section [mediagoblin] set the -following parameter:: +``./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 ... @@ -98,8 +102,8 @@ Other variables you may consider setting: `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 - "Linking assets" in the theme install section) + and MediaGoblin will symlink the current theme's assets here. See + the "Link the assets" setp in :ref:`theming-installing-section`. Making a theme @@ -109,36 +113,38 @@ 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 if necessary and -otherwise adjust if necessary):: +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 + |- theme.cfg # configuration file for this theme + |- templates/ # override templates | '- mediagoblin/ - | |- base.html # overriding mediagoblin/base.html - | '- root.html # overriding mediagoblin/root.html + | |- 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 + | | |- 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!] + | '- 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. -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. +.. 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 @@ -177,7 +183,7 @@ 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 if a new file:: +you may include one like the following:: {# # [YOUR THEME], a MediaGoblin theme @@ -224,7 +230,7 @@ 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 +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. @@ -247,7 +253,7 @@ Great, now open that file and add something like this at the end:: 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 +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. @@ -260,7 +266,7 @@ 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 + tar -cvfz yourtheme.tar.gz yourtheme Where "yourtheme" is replaced with your theme name. -- cgit v1.2.3 From 8d051cc0854c1a82d6f12251295ee44d0d463713 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Fri, 27 Jul 2012 08:45:35 -0500 Subject: Add documentation on how to alias your theme static files --- docs/source/siteadmin/deploying.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index 788b06d7..c9a429c7 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -283,6 +283,11 @@ this ``nginx.conf`` file should be modeled on the following:: 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/; + } + # Mounting MediaGoblin itself via FastCGI. location / { fastcgi_pass 127.0.0.1:26543; -- cgit v1.2.3 From cd1abb1172462488c47730d95e4484ea642bb3ba Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Fri, 27 Jul 2012 09:02:07 -0500 Subject: Reference the new theme aliasing nginx stuff in the theming documentation --- docs/source/siteadmin/deploying.rst | 2 ++ docs/source/siteadmin/theming.rst | 12 ++++++++++-- 2 files changed, 12 insertions(+), 2 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index c9a429c7..de928c82 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -222,6 +222,8 @@ test the deployment with the following command:: You should be able to connect to the machine on port 6543 in your browser to confirm that the service is operable. +.. _webserver-config: + Connect the Webserver to MediaGoblin with FastCGI ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst index b22de727..b21e2743 100644 --- a/docs/source/siteadmin/theming.rst +++ b/docs/source/siteadmin/theming.rst @@ -73,8 +73,16 @@ want to install this theme! Don't worry, it's fairly painless. Set up your webserver to serve theme assets ------------------------------------------- -FIXME - To be written. Ask on #mediagoblin in irc.freenode.net in the -meanwhile ;) +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 -- cgit v1.2.3 From 8d9aa03fbae7c1164942d05602c41cb635a44395 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 5 Aug 2012 10:14:15 -0500 Subject: Fixing grammar on telling users to run dbupdate --- docs/source/siteadmin/deploying.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index de928c82..a270c723 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -181,7 +181,7 @@ flup:: ./bin/easy_install flup This concludes the initial configuration of the development -environment. In the future, you want update your +environment. In the future, when you update your codebase, you should also run:: ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate -- cgit v1.2.3 From fafef8df2e240c3b127386af04425cca33b3d84e Mon Sep 17 00:00:00 2001 From: Aleksej Date: Sat, 18 Aug 2012 23:31:27 +0400 Subject: add titles to two pages and fix a typo in docs --- docs/source/siteadmin/theming.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst index b21e2743..98ec6de7 100644 --- a/docs/source/siteadmin/theming.rst +++ b/docs/source/siteadmin/theming.rst @@ -111,7 +111,7 @@ Other variables you may consider setting: `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" setp in :ref:`theming-installing-section`. + the "Link the assets" step in :ref:`theming-installing-section`. Making a theme -- cgit v1.2.3 From 7a690a5ae541f26321be98625a3df34847b44d5b Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 20 Aug 2012 08:54:09 -0500 Subject: Updated flatpages example in plugins.rst to reflect reality & point to flatpages docs --- docs/source/siteadmin/plugins.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst index f5a78da7..594461c0 100644 --- a/docs/source/siteadmin/plugins.rst +++ b/docs/source/siteadmin/plugins.rst @@ -79,14 +79,18 @@ 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:: +for that is ``mediagoblin.plugins.flatpagesfile`` and you would add +that to your ``.ini`` file like this:: [plugins] - [[mediagoblin.plugins.flatpages]] - # configuration for flatpages plugin here! - directory = /srv/mediagoblin/flatpages + [[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 -- cgit v1.2.3 From 3a438f5e84cef433d5c396f14dec8cd8a713e93c Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Mon, 20 Aug 2012 12:35:35 -0400 Subject: Docs tweaks This fixes some minor issues in the documentation. --- docs/source/siteadmin/configuration.rst | 10 ++++++---- docs/source/siteadmin/plugins.rst | 6 +++--- docs/source/siteadmin/relnotes.rst | 6 ++++++ 3 files changed, 15 insertions(+), 7 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/configuration.rst b/docs/source/siteadmin/configuration.rst index a3dafa4c..3da5cdd9 100644 --- a/docs/source/siteadmin/configuration.rst +++ b/docs/source/siteadmin/configuration.rst @@ -117,13 +117,15 @@ 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:: +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/ + - #mediagoblin on irc.freenode.net Celery ====== -We should point to another celery-specific section of the document -actually :) +FIXME: List Celery configuration here. diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst index 594461c0..75562d4b 100644 --- a/docs/source/siteadmin/plugins.rst +++ b/docs/source/siteadmin/plugins.rst @@ -159,13 +159,13 @@ with plugins, think about the following: For example, change:: - [[mediagoblin.plugins.flatpages]] + [[mediagoblin.plugins.flatpagesfile]] to:: - [[-mediagoblin.plugins.flatpages]] + [[-mediagoblin.plugins.flatpagesfile]] - That'll prevent the ``mediagoblin.plugins.flatpages`` plugin from + 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! diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 2efded73..025008fd 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -20,6 +20,12 @@ If you're upgrading from a previous release, please read it carefully, or at least skim over it. +0.3.1 +===== + +FIXME: Needs to be written + + 0.3.0 ===== -- cgit v1.2.3 From 0346518e35e76b56ac1effcfdea7f8d9596b3333 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Tue, 21 Aug 2012 15:37:16 -0500 Subject: Release notes for 0.3.1 --- docs/source/siteadmin/relnotes.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 025008fd..e0d28656 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -23,7 +23,17 @@ carefully, or at least skim over it. 0.3.1 ===== -FIXME: Needs to be written +As usual in this release you should be sure to run `bin/gmg dbupdate` +to upgrade the database to the latest schema. There are not major +changes other than this that you need to do to make your present +MediaGoblin instance continue to work. + +However, MediaGoblin now also includes theming support, which you can +read about in the section :ref:`_theming_chapter`. 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. 0.3.0 -- cgit v1.2.3 From 9e579cde816397be5a680725f86f7c3a0d603810 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Wed, 22 Aug 2012 17:47:15 -0400 Subject: Fix relnotes for 0.3.1. --- docs/source/siteadmin/relnotes.rst | 36 +++++++++++++++++++++++++----------- 1 file changed, 25 insertions(+), 11 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index e0d28656..1b70b31c 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -23,17 +23,31 @@ carefully, or at least skim over it. 0.3.1 ===== -As usual in this release you should be sure to run `bin/gmg dbupdate` -to upgrade the database to the latest schema. There are not major -changes other than this that you need to do to make your present -MediaGoblin instance continue to work. - -However, MediaGoblin now also includes theming support, which you can -read about in the section :ref:`_theming_chapter`. 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. +**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 -- cgit v1.2.3 From 34a853133f6b5aa4a368053489c7c7f2838eec2b Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Sat, 29 Sep 2012 20:35:49 +0200 Subject: Added note about libasound2-dev to docs. --- docs/source/siteadmin/media-types.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index d062da95..40e54c56 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -96,6 +96,13 @@ On Debianoid systems, run:: sudo apt-get install libsndfile1-dev +.. note:: + scikits.audiolab will display a warning every time it's imported if you don + not compile it with alsa support. Alsa support is not necessary for the GNU + MediaGoblin application, but if you do not wish to have the alsa warnings + from audiolab pop up everywhere you should also install ``libasound2-dev`` + before you install scikits.audiolab. + Then install ``scikits.audiolab`` for the spectrograms:: ./bin/pip install scikits.audiolab -- cgit v1.2.3 From 8518e95eb64ff2864d7880f8bfff9df1828fb848 Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Sat, 29 Sep 2012 20:39:17 +0200 Subject: Grammar re: libasound2-dev --- docs/source/siteadmin/media-types.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index 40e54c56..5653217f 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -97,11 +97,11 @@ On Debianoid systems, run:: sudo apt-get install libsndfile1-dev .. note:: - scikits.audiolab will display a warning every time it's imported if you don + 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 to have the alsa warnings - from audiolab pop up everywhere you should also install ``libasound2-dev`` - before you install scikits.audiolab. + 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:: -- cgit v1.2.3 From 4d8a3cd808a309b250df40f64bb862fdb5ede434 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 19 Nov 2012 12:17:44 -0600 Subject: Suggest checking out the wiki for additional recipes --- docs/source/siteadmin/deploying.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index a270c723..dc0a4c67 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -32,6 +32,11 @@ GNU/Linux distro. install. If instead you want to join in as a contributor, see our `Hacking HOWTO `_ 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 `_. + Prepare System -------------- -- cgit v1.2.3 From 60389b21f5d24acf6faf08c225da16b3f8d7de18 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Tue, 20 Nov 2012 09:25:41 +0100 Subject: Purge routes package from MG (#507) We were not actually using the routes package anymore, but it was still mentioned in the documention. Adapt the plugin documentation to actually represent reality, although I don't like the API design. (but this is for another day) Signed-off-by: Sebastian Spaeth --- docs/source/siteadmin/codebase.rst | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/codebase.rst b/docs/source/siteadmin/codebase.rst index 3ef91290..22f4e18b 100644 --- a/docs/source/siteadmin/codebase.rst +++ b/docs/source/siteadmin/codebase.rst @@ -68,8 +68,6 @@ Software Stack * `WebOb `_: nice abstraction layer from HTTP requests, responses and WSGI bits - * `Routes `_: for URL routing - * `Beaker `_: for handling sessions and caching -- cgit v1.2.3 From c356dc16351b33cc60cc95d6a5836ffaceffc5eb Mon Sep 17 00:00:00 2001 From: Elrond Date: Tue, 20 Nov 2012 14:32:29 +0100 Subject: Very small typo fix in deploying docs. Thanks to #mediagoblin. --- docs/source/siteadmin/deploying.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index dc0a4c67..0eb67be4 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -170,7 +170,7 @@ And set up the in-package virtualenv:: 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 + 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. @@ -178,7 +178,7 @@ 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. +your preferred method. Assuming you are going to deploy with FastCGI, you should also install flup:: -- cgit v1.2.3 From 7989cd6e4961749a39147c9020dbae745b4f23de Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sat, 1 Dec 2012 20:31:18 +0100 Subject: docs: Add trim_whitespaces plugin to relnotes and documentation Rather than mentioning a hypothetical module restrictfive, we use the existing plugin mediagoblin-licenses that people can install. Also, mention that plugin in the release notes. Signed-off-by: Sebastian Spaeth --- docs/source/siteadmin/plugins.rst | 22 +++++++++++++--------- docs/source/siteadmin/relnotes.rst | 6 ++++++ 2 files changed, 19 insertions(+), 9 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst index 75562d4b..baca381d 100644 --- a/docs/source/siteadmin/plugins.rst +++ b/docs/source/siteadmin/plugins.rst @@ -44,29 +44,33 @@ If the plugin is available on the `Python Package Index pip install For example, if we wanted to install the plugin named -"mediagoblin-restrictfive", we would do:: +"mediagoblin-licenses" (which allows you to customize the licenses you +offer for your media), we would do:: - pip install mediagoblin-restrictfive + 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. + 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-restrictfive" plugin had the Python -package path ``restrictfive``, then you would add ``restrictfive`` to +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] - [[restrictfive]] + [[mediagoblin_licenses]] + license_01=abbrev1, name1, http://url1 + license_02=abbrev2, name1, http://url2 Configuring plugins @@ -112,7 +116,7 @@ Removing plugins To remove a plugin, use ``pip uninstall``. For example:: - pip uninstall mediagoblin-restrictfive + pip uninstall mediagoblin-licenses .. Note:: diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 1b70b31c..56267eb1 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -49,6 +49,12 @@ carefully, or at least skim over it. See :ref:`core-plugin-section` for plugin documentation +* **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 0.3.0 ===== -- cgit v1.2.3 From 9d5cd0b924fe790d27b4941c5d226fc7bde03741 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Fri, 14 Dec 2012 18:29:00 -0600 Subject: Adding info to the docs about running dbupdate Both adding info to run it when adding new media types, and adding info that you might need to stop mediagoblin before you run these commands. --- docs/source/siteadmin/deploying.rst | 6 ++++++ docs/source/siteadmin/media-types.rst | 9 +++++++++ 2 files changed, 15 insertions(+) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index 0eb67be4..91406f96 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -191,6 +191,12 @@ 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 --------------------------- diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index 5653217f..3b46c1b6 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -43,6 +43,15 @@ 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? =============================================================== -- cgit v1.2.3 From cacb6feae48fd2657f02d85dbe949580d0fa6b5b Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sat, 15 Dec 2012 21:00:41 +0100 Subject: Release note 0.3.2 blurb On MongoDB... --- docs/source/siteadmin/relnotes.rst | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 56267eb1..3e09078e 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -19,6 +19,24 @@ 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.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. + + +**New features** + +* TO BE FILLED IN BEFORE RELEASE :-) + +* **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 + 0.3.1 ===== @@ -49,12 +67,6 @@ carefully, or at least skim over it. See :ref:`core-plugin-section` for plugin documentation -* **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 0.3.0 ===== -- cgit v1.2.3 From 5ef7ab084f246b81897e248590be3a61898adc77 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 20 Dec 2012 08:18:19 -0600 Subject: Added documentation on how to add STL support, and notes on running ./bin/gmg dbupdate --- docs/source/siteadmin/media-types.rst | 36 +++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index 3b46c1b6..26852842 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -77,6 +77,12 @@ good/bad/ugly). On Debianoid systems:: gstreamer0.10-ffmpeg +Add ``mediagoblin.media_types.video`` to the ``media_types`` list in your +``mediagoblin_local.ini`` and restart MediaGoblin. + +Run:: + ./bin/gmg dbupdate + Now you should be able to submit videos, and mediagoblin should transcode them. @@ -117,8 +123,12 @@ 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. You should now be able to -upload and listen to audio files! +``mediagoblin_local.ini`` and restart MediaGoblin. + +Run:: + ./bin/gmg dbupdate + +You should now be able to upload and listen to audio files! Ascii art @@ -140,4 +150,26 @@ the list would look like this:: media_types = mediagoblin.media_types.image, mediagoblin.media_types.ascii +Run:: + ./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 `_ 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:: + ./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! -- cgit v1.2.3 From 3fe3b2229c82fd894bc4d3e8effdf26cfc7780ea Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 20 Dec 2012 08:22:49 -0600 Subject: Docs fix: Adding proper blank line after the "Run::" --- docs/source/siteadmin/media-types.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index 26852842..8fbce5e4 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -81,6 +81,7 @@ Add ``mediagoblin.media_types.video`` to the ``media_types`` list in your ``mediagoblin_local.ini`` and restart MediaGoblin. Run:: + ./bin/gmg dbupdate Now you should be able to submit videos, and mediagoblin should @@ -126,6 +127,7 @@ Add ``mediagoblin.media_types.audio`` to the ``media_types`` list in your ``mediagoblin_local.ini`` and restart MediaGoblin. Run:: + ./bin/gmg dbupdate You should now be able to upload and listen to audio files! @@ -151,6 +153,7 @@ the list would look like this:: media_types = mediagoblin.media_types.image, mediagoblin.media_types.ascii Run:: + ./bin/gmg dbupdate Now any .txt file you uploaded will be processed as ascii art! @@ -169,6 +172,7 @@ Add ``mediagoblin.media_types.stl`` to the ``media_types`` list in your ``mediagoblin_local.ini`` and restart MediaGoblin. Run:: + ./bin/gmg dbupdate You should now be able to upload .obj and .stl files and MediaGoblin -- cgit v1.2.3 From 1f01df1dfc891e900e659db84ef840138b60d160 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 20 Dec 2012 09:48:47 -0600 Subject: 0.3.2 release notes --- docs/source/siteadmin/relnotes.rst | 59 +++++++++++++++++++++++++++++++++++++- 1 file changed, 58 insertions(+), 1 deletion(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 3e09078e..ef164cbb 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -25,10 +25,18 @@ carefully, or at least skim over it. 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** + +1. Make sure to run ``bin/gmg dbuptdate`` after upgrading. + **New features** -* TO BE FILLED IN BEFORE RELEASE :-) +* **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** @@ -37,6 +45,55 @@ MongoDB-based MediaGoblin instance to the newer SQL-based system. 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 `_ + which makes use of it, and there are some demo applications between + `automgtic `_, an + automatic media uploader for your desktop + and `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 ===== -- cgit v1.2.3 From 5c99cd01a70f2d597ac7669e8d944ddf79b05281 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 20 Dec 2012 13:54:03 -0600 Subject: Fixing tyop'ed "dbupdate" --- docs/source/siteadmin/relnotes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index ef164cbb..25d4d83f 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -27,7 +27,7 @@ MongoDB-based MediaGoblin instance to the newer SQL-based system. **Do this to upgrade** -1. Make sure to run ``bin/gmg dbuptdate`` after upgrading. +1. Make sure to run ``bin/gmg dbupdate`` after upgrading. **New features** -- cgit v1.2.3 From 42ce372e38b28d6e01da76b05d6924d04c2710ae Mon Sep 17 00:00:00 2001 From: Mike Linksvayer Date: Thu, 20 Dec 2012 12:52:31 -0800 Subject: actual upgrade instructions --- docs/source/siteadmin/relnotes.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 25d4d83f..55a8279d 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -27,7 +27,19 @@ MongoDB-based MediaGoblin instance to the newer SQL-based system. **Do this to upgrade** -1. Make sure to run ``bin/gmg dbupdate`` after upgrading. + # 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** -- cgit v1.2.3 From 53f528cfeaab5fc146844b6d7d85997c92cfd979 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Thu, 15 Nov 2012 16:57:33 +0100 Subject: purge webob from docs and replace with werkzeug --- docs/source/siteadmin/codebase.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/codebase.rst b/docs/source/siteadmin/codebase.rst index 22f4e18b..73e938e7 100644 --- a/docs/source/siteadmin/codebase.rst +++ b/docs/source/siteadmin/codebase.rst @@ -65,7 +65,7 @@ Software Stack `Paste Script `_: we'll use this for configuring and launching the application - * `WebOb `_: nice abstraction layer + * `werkzeug `_: nice abstraction layer from HTTP requests, responses and WSGI bits * `Beaker `_: for handling sessions and -- cgit v1.2.3 From 8d19cb2445e2aa1f53431da26d866bf9b5e25872 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 16 Nov 2012 11:32:35 +0100 Subject: Don't require webob as dependency It is pushing up the daisies. Also relnote the change. --- docs/source/siteadmin/relnotes.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 25d4d83f..9b45f642 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -19,6 +19,15 @@ 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. +WIP +===== + +**New features** + +**Other changed** + +* Dependency list has been reduced not requireing the "webob" package anymore. + 0.3.2 ===== -- cgit v1.2.3 From b0c8328e547288028e7e43f0ceb1fa9f7c8dac4a Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 30 Nov 2012 10:10:35 +0100 Subject: Move db.sql.models* to db.models* --- docs/source/siteadmin/relnotes.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 9b45f642..7d480d90 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -26,6 +26,9 @@ WIP **Other changed** +* Plugin writers: Internal restructuring led to mediagoblin.db.sql* be + mediagoblin.db.* starting from 0.3.3 + * Dependency list has been reduced not requireing the "webob" package anymore. 0.3.2 -- cgit v1.2.3 From 3a8b18f85b9affca46a433607d7d9ae723380b94 Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Fri, 25 Jan 2013 21:43:49 +0100 Subject: Updated video apt-get to not use glob Also changed some literal blocks to code-blocks --- docs/source/siteadmin/media-types.rst | 34 ++++++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 8 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index 8fbce5e4..23d3f3b9 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -71,16 +71,24 @@ 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:: +good/bad/ugly). On Debianoid systems - sudo apt-get install python-gst0.10 gstreamer0.10-plugins-{base,bad,good,ugly} \ +.. 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:: +Run + +.. code-block:: bash ./bin/gmg dbupdate @@ -108,7 +116,9 @@ To install these on Debianoid systems, run:: 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:: +On Debianoid systems, run + +.. code-block:: bash sudo apt-get install libsndfile1-dev @@ -126,7 +136,9 @@ Then install ``scikits.audiolab`` for the spectrograms:: Add ``mediagoblin.media_types.audio`` to the ``media_types`` list in your ``mediagoblin_local.ini`` and restart MediaGoblin. -Run:: +Run + +.. code-block:: bash ./bin/gmg dbupdate @@ -138,7 +150,9 @@ Ascii art To enable ascii art support, first install the `chardet `_ -library, which is necessary for creating thumbnails of ascii art:: +library, which is necessary for creating thumbnails of ascii art + +.. code-block:: bash ./bin/easy_install chardet @@ -152,7 +166,9 @@ the list would look like this:: media_types = mediagoblin.media_types.image, mediagoblin.media_types.ascii -Run:: +Run + +.. code-block:: bash ./bin/gmg dbupdate @@ -171,7 +187,9 @@ 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:: +Run + +.. code-block:: bash ./bin/gmg dbupdate -- cgit v1.2.3 From 3214c653dd72605ecacfffe13d1972c2c88506c1 Mon Sep 17 00:00:00 2001 From: Elrond Date: Sat, 26 Jan 2013 19:20:18 +0100 Subject: Docs: Create new area for developers. We need some "Part" for developers. Currently, it's named "Part 4: Developer's Zone". But we should come up with a better name soon. Moved the codebase docs in there for starters. --- docs/source/siteadmin/codebase.rst | 158 ------------------------------------- 1 file changed, 158 deletions(-) delete mode 100644 docs/source/siteadmin/codebase.rst (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/codebase.rst b/docs/source/siteadmin/codebase.rst deleted file mode 100644 index 73e938e7..00000000 --- a/docs/source/siteadmin/codebase.rst +++ /dev/null @@ -1,158 +0,0 @@ -.. 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 - . - -.. _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 `_ - for where we hang out. - -For more information on how to get started hacking on GNU MediaGoblin, -see `the wiki `_. - - -Software Stack -============== - -* Project infrastructure - - * `Python `_: the language we're using to write - this - - * `Nose `_: - for unit tests - - * `virtualenv `_: 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 `_: SQL ORM and database - interaction library for Python. Currently we support sqlite and - postgress as backends. - -* Web application - - * `Paste Deploy `_ and - `Paste Script `_: we'll use this for - configuring and launching the application - - * `werkzeug `_: nice abstraction layer - from HTTP requests, responses and WSGI bits - - * `Beaker `_: for handling sessions and - caching - - * `Jinja2 `_: the templating engine - - * `WTForms `_: for handling, - validation, and abstraction from HTML forms - - * `Celery `_: for task queuing (resizing - images, encoding video, ...) - - * `Babel `_: Used to extract and compile - translations. - - * `Markdown (for python) `_: - implementation of `Markdown `_ - text-to-html tool to make it easy for people to write richtext - comments, descriptions, and etc. - - * `lxml `_: nice xml and html processing for - python. - -* Media processing libraries - - * `Python Imaging Library `_: - used to resize and otherwise convert images for display. - - * `GStreamer `_: (Optional, for - video hosting sites only) Used to transcode video, and in the - future, probably audio too. - - * `chardet `_: (Optional, for - ascii art hosting sites only) Used to make ascii art thumbnails. - -* Front end - - * `JQuery `_: 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. -- cgit v1.2.3 From f8107ccccc83a7b2aea3adb6f2fe55c45371c080 Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Sun, 27 Jan 2013 22:10:47 +0100 Subject: *docs* intersphinx, exception monitoring --- docs/source/siteadmin/production-deployments.rst | 46 ++++++++++++++++++++++++ 1 file changed, 46 insertions(+) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/production-deployments.rst b/docs/source/siteadmin/production-deployments.rst index 356fab7f..0ed5ac6a 100644 --- a/docs/source/siteadmin/production-deployments.rst +++ b/docs/source/siteadmin/production-deployments.rst @@ -77,6 +77,52 @@ Modify your existing MediaGoblin and application init scripts, if necessary, to prevent them from starting their own ``celeryd`` processes. +Monitor exceptions +------------------ + +This is an example config using raven_ to report exceptions and +:py:mod:`logging` messages to a sentry_ instance + +.. _raven: http://raven.readthedocs.org/ +.. _sentry: https://github.com/getsentry + +.. code-block:: ini + + [pipeline:main] + pipeline = + errors + raven + routing + + [loggers] + keys = root, sentry + + [handlers] + keys = console, sentry + + [formatters] + keys = generic + + [logger_root] + level = INFO + handlers = console, sentry + + [logger_sentry] + level = WARN + handlers = console + qualname = sentry.errors + propagate = 0 + + [handler_sentry] + class = raven.handlers.logging.SentryHandler + args = ('http://public:secret@example.com/1',) + level = WARNING + formatter = generic + + [filter:raven] + use = egg:raven#raven + dsn = http://71727ea2c69043e4bbcd793bb0115cd4:e9cedccb32d9482d81f99eeca8b1ad30@sentry.talka.tv/3 + .. _init-script: Use an Init Script -- cgit v1.2.3 From 37b48053e9f2da3a6e2378874b025ab152f6f614 Mon Sep 17 00:00:00 2001 From: pythonsnake Date: Sun, 10 Feb 2013 14:07:09 +0100 Subject: Fix bug 461 --- docs/source/siteadmin/deploying.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index 91406f96..d1300d72 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -282,6 +282,9 @@ this ``nginx.conf`` file should be modeled on the following:: # 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; -- cgit v1.2.3 From a49c741f1141e8b9ff6022ebeddc4ad335fdab8a Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 24 Feb 2013 16:37:39 -0600 Subject: Removing stray character from pythonsnake's doc change and filling comment This commit sponsored by Johannes Knabbe. Thank you! --- docs/source/siteadmin/deploying.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index d1300d72..9b2324ae 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -282,8 +282,9 @@ this ``nginx.conf`` file should be modeled on the following:: # 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;· + # 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; -- cgit v1.2.3 From f3f530286ff576a3120e29f734aff0b7b7fe882c Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Sun, 3 Mar 2013 02:32:03 +0100 Subject: Updated raven plugin - Added wrap_wsgi, celery_setup, celery_logging_setup hooks - Updated raven plugin docs - Updated production considerations docs - Added raven logging setup --- docs/source/siteadmin/production-deployments.rst | 47 +++--------------------- 1 file changed, 6 insertions(+), 41 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/production-deployments.rst b/docs/source/siteadmin/production-deployments.rst index 0ed5ac6a..3e9431c9 100644 --- a/docs/source/siteadmin/production-deployments.rst +++ b/docs/source/siteadmin/production-deployments.rst @@ -77,51 +77,16 @@ Modify your existing MediaGoblin and application init scripts, if necessary, to prevent them from starting their own ``celeryd`` processes. -Monitor exceptions ------------------- - -This is an example config using raven_ to report exceptions and -:py:mod:`logging` messages to a sentry_ instance - -.. _raven: http://raven.readthedocs.org/ -.. _sentry: https://github.com/getsentry - -.. code-block:: ini - - [pipeline:main] - pipeline = - errors - raven - routing - - [loggers] - keys = root, sentry - - [handlers] - keys = console, sentry - - [formatters] - keys = generic +.. _sentry: - [logger_root] - level = INFO - handlers = console, sentry +Set up sentry to monitor exceptions +----------------------------------- - [logger_sentry] - level = WARN - handlers = console - qualname = sentry.errors - propagate = 0 +We have a plugin for `raven`_ integration, see the ":doc:`/plugindocs/raven`" +documentation. - [handler_sentry] - class = raven.handlers.logging.SentryHandler - args = ('http://public:secret@example.com/1',) - level = WARNING - formatter = generic +.. _`raven`: http://raven.readthedocs.org - [filter:raven] - use = egg:raven#raven - dsn = http://71727ea2c69043e4bbcd793bb0115cd4:e9cedccb32d9482d81f99eeca8b1ad30@sentry.talka.tv/3 .. _init-script: -- cgit v1.2.3 From 8da84493328a029649e146b8e6fcc95011783b8b Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sat, 9 Mar 2013 12:18:36 -0600 Subject: tyop fix in docs, lazyserer.sh->lazyserver.sh This commit sponsored by S J Bennett. Thanks! --- docs/source/siteadmin/production-deployments.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/production-deployments.rst b/docs/source/siteadmin/production-deployments.rst index 3e9431c9..1a32d95e 100644 --- a/docs/source/siteadmin/production-deployments.rst +++ b/docs/source/siteadmin/production-deployments.rst @@ -52,7 +52,7 @@ as the basis for your script: :: Separate Celery --------------- -While the ``./lazyserer.sh`` configuration provides an efficient way to +While the ``./lazyserver.sh`` configuration provides an efficient way to start using a MediaGoblin instance, it is not suitable for production deployments for several reasons: -- cgit v1.2.3 From 6e2dcbffaf1ed0a8d83a7998796c5faf8980afd3 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 11 Mar 2013 12:34:02 -0500 Subject: 0.3.3 release notes --- docs/source/siteadmin/relnotes.rst | 59 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 57 insertions(+), 2 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 7d480d90..455e7397 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -19,17 +19,72 @@ 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. -WIP +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:: + + [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 releae. If +you run into problems, don't hesitate to join #mediagoblin on +irc.freenode.net and we'll try to help. + **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 icon 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 now now 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! + **Other changed** * Plugin writers: Internal restructuring led to mediagoblin.db.sql* be mediagoblin.db.* starting from 0.3.3 -* Dependency list has been reduced not requireing the "webob" package anymore. +* Dependency list has been reduced not requiring the "webob" package anymore. + +* And many small fixes/improvements, too numerous to list! + 0.3.2 ===== -- cgit v1.2.3 From a28c6c4c48cf525621d90879449908cd7fe18169 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 11 Mar 2013 13:35:59 -0500 Subject: Minor release note changes, as suggested by Elrond. This commit sponsored by Martin Ansdell-Smith. Thanks! --- docs/source/siteadmin/relnotes.rst | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 455e7397..21067e75 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -32,9 +32,10 @@ carefully, or at least skim over it. [[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 releae. If -you run into problems, don't hesitate to join #mediagoblin on -irc.freenode.net and we'll try to help. +it as some theme related things may have changed in this release. If +you run into problems, don't hesitate to +`contact us `_ +(IRC is often best). **New features** @@ -56,8 +57,8 @@ irc.freenode.net and we'll try to help. * As a demonstration of new template hooks for plugin authoring, openstreetmap support now moved to a plugin! -* Method to add icon to collections switched from icon of paperclip to - button with "add to collection" text. +* 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! @@ -65,10 +66,10 @@ irc.freenode.net and we'll try to help. waste gobs of memory. * Video transcoding now optional for videos that meet certain - criteria. By default, MediaGoblin will now now 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. + criteria. By default, MediaGoblin will now 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 @@ -76,7 +77,7 @@ irc.freenode.net and we'll try to help. * Video player now responsive; better for mobile! -**Other changed** +**Other changes** * Plugin writers: Internal restructuring led to mediagoblin.db.sql* be mediagoblin.db.* starting from 0.3.3 -- cgit v1.2.3 From 70177c1febb9485a02ca46a36d95eff45c14e599 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 11 Mar 2013 15:18:24 -0500 Subject: You can also DELETE accounts now --- docs/source/siteadmin/relnotes.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 21067e75..5931a467 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -77,6 +77,9 @@ you run into problems, don't hesitate to * 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 -- cgit v1.2.3 From fda5ea7aaa6b3879a681f5f1b2da2fe41c6e315c Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Tue, 12 Mar 2013 11:49:39 -0500 Subject: "will now" -> "will not" tyop caught by AVRS... fixed, thanks! --- docs/source/siteadmin/relnotes.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 5931a467..84ec09b5 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -62,13 +62,13 @@ you run into problems, don't hesitate to * Bug where videos often failed to produce a proper thumbnail fixed! -* Copying around files in mediagoblin now much more efficient, doesn't +* 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 now 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 + 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 -- cgit v1.2.3 From 997ef976699b8d10908ee908cb62b9587d023f92 Mon Sep 17 00:00:00 2001 From: Elrond Date: Tue, 19 Mar 2013 18:52:14 +0100 Subject: Improve release notes formatting. The geolocation ini sample needed more indenting and got a nice "code-block:: ini". --- docs/source/siteadmin/relnotes.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 84ec09b5..6962dc5a 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -26,10 +26,12 @@ carefully, or at least skim over it. 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:: + following to your config file: - [plugins] - [[mediagoblin.plugins.geolocation]] + .. 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 -- cgit v1.2.3 From 71ef20078cc061317eaf42f20bdc905bcce3ab2a Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 10 Apr 2013 10:52:39 -0500 Subject: Adding some help about what to do if flup flakes out on you --- docs/source/siteadmin/deploying.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index 9b2324ae..77e60037 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -185,6 +185,11 @@ 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:: -- cgit v1.2.3 From a80ebf3b64dce807d84ab3993984c211f55b47db Mon Sep 17 00:00:00 2001 From: Alon Levy Date: Wed, 27 Mar 2013 12:21:10 +0200 Subject: add pdf media type The new media type supports pdf and a subset of media recognized by libreoffice via unoconv. Every document added goes through: * conversion to pdf with unoconv if not already a pdf * creation of thumbnail and medium sized image, and pdfinfo generates some information (even for unoconv produces docs - should fix this) Poppler (pdftocairo, pdfinfo) is used. http://poppler.freedesktop.org/ A working but uglified pdf.js integration exists, which is enabled by setting pdf.pdf_js=true mediagoblin_local.ini (disabled in mediagoblin.ini) Adds one test to the test_submission test suite, and another separate test_pdf suite. The tests are only run if media_types.pdf.processing.check_prerequisites passes, so the test suite will not require any extra package. TODO: make test suite say 'skipped' in that case instead of just 'ok' Signed-off-by: Alon Levy --- docs/source/siteadmin/media-types.rst | 37 +++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index 23d3f3b9..264dc4fc 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -195,3 +195,40 @@ Run 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 pdftocairo, pdfinfo, +unoconv with headless support. All executables must be on your execution path. + +To install this on Fedora: + +.. code-block:: bash + + sudo yum install -y ppoppler-utils unoconv libreoffice-headless + +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 + + -- cgit v1.2.3 From 3606316e9d7cac12ccf9411fb63c60bb1b775eb9 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 17 Apr 2013 07:41:00 -0500 Subject: ppoppler -> poppler tyop fix --- docs/source/siteadmin/media-types.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index 264dc4fc..210094b9 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -206,7 +206,7 @@ To install this on Fedora: .. code-block:: bash - sudo yum install -y ppoppler-utils unoconv libreoffice-headless + sudo yum install -y poppler-utils unoconv libreoffice-headless pdf.js relies on git submodules, so be sure you have fetched them: -- cgit v1.2.3 From b835e15319882477e71c7b03db2c1565dd674a96 Mon Sep 17 00:00:00 2001 From: Elrond Date: Tue, 30 Apr 2013 00:24:45 +0200 Subject: Add warning about crypt/itsdangeroussecret.bin. You should not leak that file, really. --- docs/source/siteadmin/deploying.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index 77e60037..f2f71e01 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -345,3 +345,17 @@ Visit the site you've set up in your browser by visiting smaller deployments. However, for larger production deployments with larger processing requirements, see the ":doc:`production-deployments`" documentation. + + +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. -- cgit v1.2.3 From a7d2a8924edd010e707e6da17f17bc74f5db2fbd Mon Sep 17 00:00:00 2001 From: Sam Tuke Date: Mon, 6 May 2013 16:19:10 +0200 Subject: Added info about editing mediagoblin.ini Added link to Apache deployment instructions --- docs/source/siteadmin/deploying.rst | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index f2f71e01..fae4afa0 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -205,6 +205,19 @@ 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 you're mediagoblin directory is not the root directory of your vhost. + + Configure MediaGoblin to use the PostgreSQL database ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -240,11 +253,11 @@ browser to confirm that the service is operable. .. _webserver-config: -Connect the Webserver to MediaGoblin with FastCGI -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This section describes how to configure MediaGoblin to work via -FastCGI. Our configuration example will use nginx, however, you may +FastCGI 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 @@ -345,6 +358,12 @@ Visit the site you've set up in your browser by visiting 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 `_. Security Considerations -- cgit v1.2.3 From 041d2fd785f9b3e18f9fd758f91dbfa7715d317c Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Fri, 17 May 2013 15:10:34 -0500 Subject: Just word-wrapping the recent changes to the deployment docs. --- docs/source/siteadmin/deploying.rst | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index fae4afa0..9bcc0637 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -208,14 +208,18 @@ 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:: +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 you're mediagoblin directory is not the root directory of your vhost. +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 @@ -363,7 +367,8 @@ Visit the site you've set up in your browser by visiting Apache ~~~~~~ -Instructions and scripts for running MediaGoblin on an Apache server can be found on the `MediaGoblin wiki `_. +Instructions and scripts for running MediaGoblin on an Apache server +can be found on the `MediaGoblin wiki `_. Security Considerations -- cgit v1.2.3 From 8ca51d32b66b96043c8685aac1e478111612c980 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 22 May 2013 16:44:50 -0500 Subject: Move "bits" templates with dashes in them to underscores Moved all references and also added a note to our release notes. This commit sponsored by Juan Rodriguez. Thank you! --- docs/source/siteadmin/relnotes.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 04863ec6..5d342ef1 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -19,6 +19,22 @@ 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 +===== + +**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. + + 0.3.3 ===== -- cgit v1.2.3 From 24ede04415df1a79da83e2716ab3c714e2080563 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 23 May 2013 13:43:04 -0500 Subject: Documentation changes to reflect new plugin assetlink stuff - updated old theme assetlink section to reflect new location of ./bin/gmg assetlink and removed comment about the plugin command being temporary. - Added a new section to the standard config file on where to put the plugin_static section - Added release notes about said section This commit sponsored by Thomas Webber. Thanks, Dad! --- docs/source/siteadmin/deploying.rst | 5 +++++ docs/source/siteadmin/relnotes.rst | 17 +++++++++++++++++ docs/source/siteadmin/theming.rst | 2 +- 3 files changed, 23 insertions(+), 1 deletion(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index 9bcc0637..0ee6b5b4 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -327,6 +327,11 @@ this ``nginx.conf`` file should be modeled on the following:: 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; diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 5d342ef1..d25771d3 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -22,6 +22,21 @@ 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/; + } + **For theme authors** If you have your own theme or you have any "user modified templates", @@ -34,6 +49,8 @@ please note the following: You can easily customize this to give a welcome page appropriate to your site. +**New features** + 0.3.3 ===== diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst index 98ec6de7..11ae3875 100644 --- a/docs/source/siteadmin/theming.rst +++ b/docs/source/siteadmin/theming.rst @@ -51,7 +51,7 @@ want to install this theme! Don't worry, it's fairly painless. 5. Link the assets so that they can be served by your web server:: - $ ./bin/gmg theme assetlink + $ ./bin/gmg assetlink .. Note:: -- cgit v1.2.3 From 5471e08e7eb27872d7a656ed87911be307dd8290 Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Fri, 24 May 2013 23:07:09 +0200 Subject: Improved docs - Fixed an outdated URL - Rewrote "Separate Celery" section - Changed literal blocks to bash code-blocks - Changed wording when referring to the MediaGoblin WSGI application --- docs/source/siteadmin/production-deployments.rst | 64 +++++++++++++++--------- 1 file changed, 39 insertions(+), 25 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/production-deployments.rst b/docs/source/siteadmin/production-deployments.rst index 1a32d95e..839d3ce5 100644 --- a/docs/source/siteadmin/production-deployments.rst +++ b/docs/source/siteadmin/production-deployments.rst @@ -22,12 +22,14 @@ MediaGoblin in actual production environments. Consider 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 +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: :: +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 \ @@ -41,7 +43,9 @@ 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: :: +as the basis for your script: + +.. code-block:: bash CELERY_ALWAYS_EAGER=false \ /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ @@ -52,30 +56,40 @@ as the basis for your script: :: Separate Celery --------------- -While the ``./lazyserver.sh`` configuration provides an efficient way to -start using a MediaGoblin instance, it is not suitable for production -deployments for several reasons: +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/ + -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. +.. [#f-mediagoblin-wsgi-app] The MediaGoblin WSGI application is the part that + of MediaGoblin that processes HTTP requests. -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. +To launch Celery separately from the MediaGoblin WSGI application: -Build an :ref:`init script ` around the following -command:: +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 - CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd + .. code-block:: bash -Modify your existing MediaGoblin and application init scripts, if -necessary, to prevent them from starting their own ``celeryd`` -processes. + CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd .. _sentry: @@ -102,7 +116,7 @@ These are scripts provided by the MediaGoblin community: Debian * `GNU MediaGoblin init scripts - `_ + `_ by `Joar Wandborg `_ Arch Linux -- cgit v1.2.3 From b21220e931e80fa9005f71c026eaa66f5ea225f4 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 29 May 2013 14:13:12 -0500 Subject: Actually link to the release notes when we say "see the release notes". This commit sponsored by Brian Kemp. Thank you! --- docs/source/siteadmin/relnotes.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index d25771d3..9c9d311c 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -11,6 +11,8 @@ Dedication along with this software. If not, see . +.. _release-notes: + ============= Release Notes ============= -- cgit v1.2.3 From 376dcbb493a31e8af4de4ba05c70b17900af04e1 Mon Sep 17 00:00:00 2001 From: Alon Levy Date: Wed, 12 Jun 2013 22:42:58 -0400 Subject: media-types.rst: clarify the pdf media type requirements Explain that it works fine without libreoffice, just with reduced functionality. Signed-off-by: Alon Levy --- docs/source/siteadmin/media-types.rst | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index 210094b9..1527bc70 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -199,8 +199,16 @@ 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 pdftocairo, pdfinfo, -unoconv with headless support. All executables must be on your execution path. +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: @@ -208,6 +216,9 @@ To install this on Fedora: 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 -- cgit v1.2.3 From 51702d5b7d4f27fc5131f638269f7e7344a382b0 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 16 Jun 2013 19:39:03 -0500 Subject: Documenting most of the the many new features in the release notes. --- docs/source/siteadmin/relnotes.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'docs/source/siteadmin') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 9c9d311c..7b6d8353 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -39,6 +39,13 @@ carefully, or at least skim over it. 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", @@ -51,7 +58,23 @@ please note the following: 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 -- cgit v1.2.3