5 GNU MediaGoblin supports plugins that allow you to augment MediaGoblin's
8 This chapter covers discovering, installing, configuring and removing
15 MediaGoblin comes with core plugins. Core plugins are located in the
16 ``mediagoblin.plugins`` module of the MediaGoblin code. Because they
17 come with MediaGoblin, you don't have to install them, but you do have
18 to add them to your config file if you're interested in using them.
20 You can also write your own plugins and additionally find plugins
21 elsewhere on the Internet. Once you find a plugin you like, you need
22 to first install it, then add it to your configuration.
24 .. todo: how do you find plugins on the internet?
33 MediaGoblin core plugins don't need to be installed because they come
34 with MediaGoblin. Further, when you upgrade MediaGoblin, you will also
35 get updates to the core plugins.
41 If the plugin is available on the `Python Package Index
42 <http://pypi.python.org/pypi>`_, then you can install the plugin with pip::
44 pip install <plugin-name>
46 For example, if we wanted to install the plugin named
47 "mediagoblin-restrictfive", we would do::
49 pip install mediagoblin-restrictfive
53 If you're using a virtual environment, make sure to activate the
54 virtual environment before installing with pip. Otherwise the
55 plugin may get installed in a different environment than the one
56 MediaGoblin is installed in.
58 Once you've installed the plugin software, you need to tell
59 MediaGoblin that this is a plugin you want MediaGoblin to use. To do
60 that, you edit the ``mediagoblin.ini`` file and add the plugin as a
61 subsection of the plugin section.
63 For example, say the "mediagoblin-restrictfive" plugin had the Python
64 package path ``restrictfive``, then you would add ``restrictfive`` to
65 the ``plugins`` section as a subsection::
75 Configuration for a plugin goes in the subsection for that plugin. Core
76 plugins are documented in the administration guide. Other plugins
77 should come with documentation that tells you how to configure them.
79 Example 1: Core MediaGoblin plugin
81 If you wanted to use the core MediaGoblin flatpages plugin, the module
82 for that is ``mediagoblin.plugins.flatpagesfile`` and you would add
83 that to your ``.ini`` file like this::
87 [[mediagoblin.plugins.flatpagesfile]]
88 # configuration for flatpagesfile plugin here!
89 about-view = '/about', about.html
90 terms-view = '/terms', terms.html
92 (Want to know more about the flatpagesfile plugin? See
93 :ref:`flatpagesfile-chapter`)
95 Example 2: Plugin that is not a core MediaGoblin plugin
97 If you installed a hypothetical restrictfive plugin which is in the
98 module ``restrictfive``, your ``.ini`` file might look like this (with
99 comments making the bits clearer)::
104 # configuration for restrictfive here!
106 Check the plugin's documentation for what configuration options are
113 To remove a plugin, use ``pip uninstall``. For example::
115 pip uninstall mediagoblin-restrictfive
119 If you're using a virtual environment, make sure to activate the
120 virtual environment before uninstalling with pip. Otherwise the
121 plugin may get installed in a different environment.
130 Core plugins get upgraded automatically when you upgrade MediaGoblin
131 because they come with MediaGoblin.
137 For plugins that you install with pip, you can upgrade them with pip::
139 pip install -U <plugin-name>
141 The ``-U`` tells pip to upgrade the package.
144 Troubleshooting plugins
145 =======================
147 Sometimes plugins just don't work right. When you're having problems
148 with plugins, think about the following:
150 1. Check the log files.
152 Some plugins will log errors to the log files and you can use that
153 to diagnose the problem.
155 2. Try running MediaGoblin without that plugin.
157 It's easy to disable a plugin from MediaGoblin. Add a ``-`` to the
158 name in your config file.
160 For example, change::
162 [[mediagoblin.plugins.flatpages]]
166 [[-mediagoblin.plugins.flatpages]]
168 That'll prevent the ``mediagoblin.plugins.flatpages`` plugin from
171 3. If it's a core plugin that comes with MediaGoblin, ask us for help!
173 If it's a plugin you got from somewhere else, ask them for help!