1 .. MediaGoblin Documentation
3 Written in 2012 by MediaGoblin contributors
5 To the extent possible under law, the author(s) have dedicated all
6 copyright and related and neighboring rights to this software to
7 the public domain worldwide. This software is distributed without
10 You should have received a copy of the CC0 Public Domain
11 Dedication along with this software. If not, see
12 <http://creativecommons.org/publicdomain/zero/1.0/>.
20 This chapter has important information for releases in it.
21 If you're upgrading from a previous release, please read it
22 carefully, or at least skim over it.
27 **Do this to upgrade**
29 1. Update to the latest release. If checked out from git, run:
30 ``git fetch && git checkout -q v0.7.0 && git submodule update``
32 ``./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate``
34 That's it, probably! If you run into problems, don't hesitate to
35 `contact us <http://mediagoblin.org/pages/join.html>`_
40 - New mobile upload API making use of the
41 `Pump API <https://github.com/e14n/pump.io/blob/master/API.md>`_
42 (which will be the foundation for MediaGoblin's federation)
43 - New theme: Sandy 70s Speedboat!
45 - Metadata features! We also now have a json-ld context.
47 - Many improvements for archival institutions, including metadata
48 support and featuring items on the homepage. With the (new!)
49 archivalook plugin enabled, featuring media is possible.
50 Additionally, metadata about the particular media item will show up
53 In the future these plugins may be separated, but for now they have
54 come together as part of the same plugin.
56 - There is a new gmg subcommand called batchaddmedia that allows for
57 uploading many files at once. This is aimed to be useful for
58 archival institutions and groups where there is an already existing
59 and large set of available media that needs to be included.
60 - Speaking of, the call to postgres in the makefile is fixed.
61 - We have a new, generic media-page context hook that allows for
62 adding context depending on the type of media.
63 - Tired of video thumbnails breaking during processing all the time?
64 Good news, everyone! Video thumbnail generation should not fail
65 frequently anymore. (We think...)
66 - You can now set default permissions for new users in the config.
68 - bootstrap.sh / gnu configuration stuff still exists, but moves to be
69 experimental-bootstrap.sh so as to not confuse newcomers. There are
70 some problems currently with the autoconf stuff that we need to work
71 out... we still have interest in supporting it, though help is
74 - MediaGoblin now checks whether or not the database is up to date
76 - Switched to `Skeleton <http://www.getskeleton.com/>`_ as a system for
78 - New gmg subcommands for administrators:
79 - A "deletemedia" command
80 - A "deleteuser" command
81 - We now have a blogging media type... it's very experimental,
82 however. Use with caution!
83 - We have switched to exifread as an external library for reading EXIF
84 data. It's basically the same thing as before, but packaged
85 separately from MediaGoblin.
86 - Many improvements to internationalization. Also (still rudimentary,
87 but existant!) RTL language support!
90 - Webfinger is now json by default; in the spec it should be xml by
91 default. We have done this because of compatibility with the pump
92 API. We are checking with upstream to see if there is a way to
93 resolve this discrepancy.
99 This is a short, bugfix release.
101 **Do this to upgrade**
103 1. Update to the latest release. If checked out from git, run:
104 ``git fetch && git checkout -q v0.6.1``
106 ``./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate``
108 This release switches the default terms of service to be off by
109 default and corrects some mistakes in the default terms of service.
111 Turning the terms of service on is very easy, just set ``show_tos`` in
112 the ``[mediagoblin]`` section of your config to ``true``.
118 **Do this to upgrade**
120 1. Update to the latest release. If checked out from git, run:
121 ``git fetch && git checkout -q v0.6.0``
123 ``./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate``
125 That's it, probably! If you run into problems, don't hesitate to
126 `contact us <http://mediagoblin.org/pages/join.html>`_
129 This tool has a lot of new tools for administrators, hence the
130 nickname "Lore of the Admin"!
134 - New tools to control how much users can upload, both as a general
135 user limit, or per file.
137 You can set this with the following options in your mediagoblin
138 config file: `upload_limit` and `max_file_size`. Both are integers
141 There is an option to control how much each individual user can
142 upload too, though an interface for this is not yet exposed. See
143 the "uploaded" field on the core__users table.
145 - MediaGoblin now contains an authentication plugin for ldap! You
146 can turn on the mediagoblin.plugins.ldap plugin to make use of
147 this. See the documentation: :ref:`ldap-plugin`
149 - There's a new command line upload tool! At long last! See
150 `./bin/gmg addmedia --help` for info on how to use this.
152 - There's now a terms of service document included in MediaGoblin.
153 It's turned on by default, but you can turn it off if you prefer,
154 just set the configuration option of `show_tos` in the [mediagoblin]
155 section of your config to false.
157 Alternately, you can override the template for the terms of service
158 document to set up your own.
160 - We have a lot of new administrative tooling features!
161 - There's a built-in privileges/permissions system now.
162 Administrators are given access to modifying these parameters
163 from a user administration panel.
164 - Users can submit reports about other problematic users or media
165 and administrators are given tools to resolve said reports and
166 ban/unban users if needed.
168 - New version of video.js is included with MediaGoblin. Slight
169 amount of skinning to match the MediaGoblin look, otherwise also
170 uses the new default skin.
172 Developer-oriented changes:
174 - New developer tool for quickly setting up a development environment
175 in `devtools/make_example_database.sh`. Requires doing a checkout
176 of our other tool `mg_dev_environments <https://gitorious.org/mediagoblin/mg-dev-environments/>`_
177 (probably in the parent Directory) though!
178 - A "foundations" framework has entered into the codebase.
179 This is mostly just relevant to coders, but it does mean that it's
180 much easier to add database structures that need some entries filled
181 automatically by default.
182 - Refactoring to the authentication code and the reprocessing code
188 v0.5.1 is a bugfix release... the steps are the same as for 0.5.1.
192 - python 2.6 compatibility restored
193 - Fixed last release's release notes ;)
199 **NOTE:** If using the API is important to you, we're in a state of
200 ransition towards a new API via the Pump API. As such, though the old
201 API still probably works, some changes have happened to the way oauth
202 works to make it more Pump-compatible. If you're heavily using
203 clients using the old API, you may wish to hold off on upgrading for
204 now. Otherwise, jump in and have fun! :)
206 **Do this to upgrade**
209 ``./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate``
212 .. mention something about new, experimental configure && make support
214 2. Note that a couple of things have changed with ``mediagoblin.ini``. First
215 we have a new Authentication System. You need to add
216 ``[[mediagoblin.plugins.basic_auth]]`` under the ``[plugins]`` section of
217 your config file. Second, media types are now plugins, so you need to add
218 each media type under the ``[plugins]`` section of your config file.
221 3. We have made a script to transition your ``mediagoblin_local.ini`` file for
222 you. This script can be found at:
224 http://mediagoblin.org/download/0.5.0_config_converter.py
226 If you run into problems, don't hesitate to
227 `contact us <http://mediagoblin.org/pages/join.html>`_
232 * As mentioned above, we now have a plugable Authentication system. You can
233 use any combination of the multiple authentication systems
234 (:ref:`basic_auth-chapter`, :ref:`persona-chapter`, :ref:`openid-chapter`)
236 * Media types are now plugins! This means that new media types will
237 be able to do new, fancy things they couldn't in the future.
238 * We now have notification support! This allows you to subscribe to media
239 comments and to be notified when someone comments on your media.
240 * New reprocessing framework! You can now reprocess failed uploads, and
241 send already processed media back to processing to re-transcode or resize
244 * Users now have the ability to change their email associated with their
246 * New oauth code as we move closer to federation support.
247 * Experimental pyconfigure support for GNU-style configue and makefile
249 * Database foundations! You can now pre-populate the database models.
250 * Way faster unit test run-time via in-memory database.
251 * All mongokit stuff has been cleaned up.
252 * Fixes for non-ascii filenames.
253 * The option to stay logged in.
254 * Mediagoblin has been upgraded to use the latest `celery <http://celeryproject.org/>`_
256 * You can now add jinja2 extensions to your config file to use in custom
258 * Fixed video permission issues.
259 * Mediagoblin docs are now hosted with multiple versions.
260 * We removed redundent tooltips from the STL media display.
261 * We are now using itsdangerous for verification tokens.
267 This is a bugfix release for 0.4.0. This only implements one major
268 fix in the newly released document support which prevented the
269 "conversion via libreoffice" feature.
271 If you were running 0.4.0 you can upgrade to v0.4.1 via a simple
272 switch and restarting mediagoblin/celery with no other actions.
274 Otherwise, follow 0.4.0 instructions.
280 **Do this to upgrade**
283 ``./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate``
285 2. See "For Theme authors" if you have a custom theme.
286 3. Note that ``./bin/gmg theme assetlink`` is now just
287 ``./bin/gmg assetlink`` and covers both plugins and assets.
288 Keep on reading to hear more about new plugin features.
289 4. If you want to take advantage of new plugins that have statically
290 served assets, you are going to need to add the new "plugin_static"
291 section to your nginx config. Basically the following for nginx::
293 # Plugin static files (usually symlinked in)
294 location /plugin_static/ {
295 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/;
298 Similarly, if you've got a modified paste config, you may want to
299 borrow the app:plugin_static section from the default paste.ini
301 5. We now use itsdangerous for sessions; if you had any references to
302 beaker in your paste config you can remove them. Again, see the
303 default paste.ini config
304 6. We also now use git submodules. Please do:
305 ``git submodule init && git submodule update``
306 You will need to do this to use the new PDF support.
308 **For theme authors**
310 If you have your own theme or you have any "user modified templates",
311 please note the following:
313 * mediagoblin/bits/ files above-content.html, body-end.html,
314 body-start.html now are renamed... they have underscores instead of
315 dashes in the filenames now :)
316 * There's a new file: ``mediagoblin/bits/frontpage_welcome.html``.
317 You can easily customize this to give a welcome page appropriate to
324 * Improved plugin system. More flexible, better documented, with a
325 new plugin authoring section of the docs.
326 * itsdangerous based sessions. No more beaker!
327 * New, experimental Piwigo-based API. This means you should be able
328 to use MediaGoblin with something like Shotwell. (Again, a word of
329 caution: this is *very experimental*!)
330 * Human readable timestamps, and the option to display the original
331 date of an image when available (available as the
332 "original_date_visible" variable)
333 * Moved unit testing system from nosetests to py.test so we can better
334 handle issues with sqlalchemy exploding with different database
335 configurations. Long story :)
336 * You can now disable the ability to post comments.
337 * Tags now can be up to length 255 characters by default.
343 **Do this to upgrade**
345 1. Make sure to run ``bin/gmg dbupdate`` after upgrading.
346 2. OpenStreetMap is now a plugin, so if you want to use it, add the
347 following to your config file:
352 [[mediagoblin.plugins.geolocation]]
354 If you have your own theme, you may need to make some adjustments to
355 it as some theme related things may have changed in this release. If
356 you run into problems, don't hesitate to
357 `contact us <http://mediagoblin.org/pages/join.html>`_
362 * New dropdown menu for accessing various features.
364 * Significantly improved URL generation. Now mediagoblin won't give
365 up on making a slug if it looks like there will be a duplicate;
366 it'll try extra hard to generate a meaningful one instead.
368 Similarly, linking to an id no longer can possibly conflict with
369 linking to a slug; /u/username/m/id:35/ is the kind of reference we
370 now use to linking to entries with ids. However, old links with
371 entries that linked to ids should work just fine with our migration.
372 The only urls that might break in this release are ones using colons
375 * New template hooks for plugin authoring.
377 * As a demonstration of new template hooks for plugin authoring,
378 openstreetmap support now moved to a plugin!
380 * Method to add media to collections switched from icon of paperclip
381 to button with "add to collection" text.
383 * Bug where videos often failed to produce a proper thumbnail fixed!
385 * Copying around files in MediaGoblin now much more efficient, doesn't
386 waste gobs of memory.
388 * Video transcoding now optional for videos that meet certain
389 criteria. By default, MediaGoblin will not transcode webm videos
390 that are smaller in resolution than the MediaGoblin defaults, and
391 MediaGoblin can also be configured to allow theora files to not be
394 * Per-user license preference option; always want your uploads to be
395 BY-SA and tired of changing that field? You can now set your
396 license preference in your user settings.
398 * Video player now responsive; better for mobile!
400 * You can now delete your account from the user preferences page if
405 * Plugin writers: Internal restructuring led to mediagoblin.db.sql* be
406 mediagoblin.db.* starting from 0.3.3
408 * Dependency list has been reduced not requiring the "webob" package anymore.
410 * And many small fixes/improvements, too numerous to list!
416 This will be the last release that is capable of converting from an earlier
417 MongoDB-based MediaGoblin instance to the newer SQL-based system.
419 **Do this to upgrade**
421 # directory of your mediagoblin install
422 cd /srv/mediagoblin.example.org
424 # copy source for this release
426 git checkout tags/v0.3.2
428 # perform any needed database updates
431 # restart your servers however you do that, e.g.,
432 sudo service mediagoblin-paster restart
433 sudo service mediagoblin-celeryd restart
438 * **3d model support!**
440 You can now upload STL and OBJ files and display them in
441 MediaGoblin. Requires a recent-ish Blender; for details see:
442 :ref:`deploying-chapter`
444 * **trim_whitespace**
446 We bundle the optional plugin trim_whitespace which reduces the size
447 of the delivered html output by reducing redundant whitespace.
449 See :ref:`core-plugin-section` for plugin documentation
453 It isn't well documented yet but we do have an API. There is an
454 `android application in progress <https://gitorious.org/mediagoblin/mediagoblin-android>`_
455 which makes use of it, and there are some demo applications between
456 `automgtic <https://github.com/jwandborg/automgtic>`_, an
457 automatic media uploader for your desktop
458 and `OMGMG <https://github.com/jwandborg/omgmg>`_, an example of
459 a web application hooking up to the API.
461 This is a plugin, so you have to enable it in your mediagoblin
462 config file by adding a section under [plugins] like::
465 [[mediagoblin.plugins.api]]
467 Note that the API works but is not nailed down... the way it is
468 called may change in future releases.
470 * **OAuth login support**
472 For applications that use OAuth to connect to the API.
474 This is a plugin, so you have to enable it in your mediagoblin
475 config file by adding a section under [plugins] like::
478 [[mediagoblin.plugins.oauth]]
482 We now have user-curated collections support. These are arbitrary
483 galleries that are customizable by users. You can add media to
484 these by clicking on the paperclip icon when logged in and looking
487 * **OpenStreetMap licensing display improvements**
489 More accurate display of OSM licensing, and less disruptive: you
490 click to "expand" the display of said licensing.
492 Geolocation is also now on by default.
494 * **Miscelaneous visual improvements**
496 We've made a number of small visual improvements including newer and
497 nicer looking thumbnails and improved checkbox placement.
504 **Do this to upgrade**
506 1. Make sure to run ``bin/gmg dbuptdate`` after upgrading.
508 2. If you set up your server config with an older version of
509 mediagoblin and the mediagoblin docs, it's possible you don't
510 have the "theme static files" alias, so double check to make
511 sure that section is there if you are having problems.
517 * **theming support**
519 MediaGoblin now also includes theming support, which you can
520 read about in the section :ref:`theming-chapter`.
524 MediaGoblin has a flatpages plugin allowing you to add pages that
525 are aren't media-related like "About this site...", "Terms of
528 See :ref:`core-plugin-section` for plugin documentation
534 This release has one important change. You need to act when
535 upgrading from a previous version!
537 This release changes the database system from MongoDB to
538 SQL(alchemy). If you want to setup a fresh instance, just
539 follow the instructions in the deployment chapter. If on
540 the other hand you want to continue to use one instance,
543 To convert your data from MongoDB to SQL(alchemy), you need
544 to follow these steps:
546 1. Make sure your MongoDB is still running and has your
547 data, it's needed for the conversion.
549 2. Configure the ``sql_engine`` URI in the config to represent
550 your target database (see: :ref:`deploying-chapter`)
552 3. You need an empty database.
554 4. Then run the following command::
556 bin/gmg [-cf mediagoblin_config.ini] convert_mongo_to_sql
558 5. Start your server and investigate.