docs/source/siteadmin/plugins.rst

   1 =========
   2  Plugins
   3 =========
   4
   5 GNU MediaGoblin supports plugins that allow you to augment MediaGoblin's
   6 behavior.
   7
   8 This chapter covers discovering, installing, configuring and removing
   9 plugins.
  10
  11
  12 Discovering plugins
  13 ===================
  14
  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.
  19
  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.
  23
  24 .. todo: how do you find plugins on the internet?
  25
  26
  27 Installing plugins
  28 ==================
  29
  30 Core plugins
  31 ------------
  32
  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.
  36
  37
  38 Other plugins
  39 -------------
  40
  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::
  43
  44     pip install <plugin-name>
  45
  46 For example, if we wanted to install the plugin named
  47 "mediagoblin-licenses" (which allows you to customize the licenses you
  48 offer for your media), we would do::
  49
  50     pip install mediagoblin-licenses
  51
  52 .. note::
  53
  54    If you're using a virtual environment, make sure to activate the
  55    virtual environment before installing with pip. Otherwise the plugin
  56    may get installed in a different environment than the one MediaGoblin
  57    is installed in. Also make sure, you use e.g. pip-2.7 if your default
  58    python (and thus pip) is python 3 (e.g. in Ubuntu and derivatives).
  59
  60 Once you've installed the plugin software, you need to tell
  61 MediaGoblin that this is a plugin you want MediaGoblin to use. To do
  62 that, you edit the ``mediagoblin.ini`` file and add the plugin as a
  63 subsection of the plugin section.
  64
  65 For example, say the "mediagoblin-licenses" plugin has the Python
  66 package path ``mediagoblin_licenses``, then you would add ``mediagoblin_licenses`` to
  67 the ``plugins`` section as a subsection::
  68
  69     [plugins]
  70
  71     [[mediagoblin_licenses]]
  72     license_01=abbrev1, name1, http://url1
  73     license_02=abbrev2, name1, http://url2
  74
  75
  76 Configuring plugins
  77 ===================
  78
  79 Configuration for a plugin goes in the subsection for that plugin. Core
  80 plugins are documented in the administration guide. Other plugins
  81 should come with documentation that tells you how to configure them.
  82
  83 Example 1: Core MediaGoblin plugin
  84
  85 If you wanted to use the core MediaGoblin flatpages plugin, the module
  86 for that is ``mediagoblin.plugins.flatpagesfile`` and you would add
  87 that to your ``.ini`` file like this::
  88
  89     [plugins]
  90
  91     [[mediagoblin.plugins.flatpagesfile]]
  92     # configuration for flatpagesfile plugin here!
  93     about-view = '/about', about.html
  94     terms-view = '/terms', terms.html
  95
  96 (Want to know more about the flatpagesfile plugin?  See
  97 :ref:`flatpagesfile-chapter`)
  98
  99 Example 2: Plugin that is not a core MediaGoblin plugin
 100
 101 If you installed a hypothetical restrictfive plugin which is in the
 102 module ``restrictfive``, your ``.ini`` file might look like this (with
 103 comments making the bits clearer)::
 104
 105     [plugins]
 106
 107     [[restrictfive]]
 108     # configuration for restrictfive here!
 109
 110 Check the plugin's documentation for what configuration options are
 111 available.
 112
 113 Once you've set up your plugin, you should be sure to update the
 114 database to accommodate the new plugins::
 115
 116   ./bin/gmg dbupdate
 117
 118
 119 Deactivating plugins
 120 ====================
 121
 122 You should be aware that once you enable a plugin, deactivating it
 123 might be a bit tricky, for migrations reasons.  In the future we may
 124 produce better tooling to accommodate this.  In short, you will need to
 125 do a bit of database surgery by:
 126
 127 - Removing all tables and indexes installed by the plugin
 128 - Removing the plugin's migration head id from the `alembic_version`
 129   table.  (You might be able to determine which to remove via
 130   examining the output of `./bin/gmg alembic heads`)
 131
 132 Note that this is a VERY TRICKY process, and you should be sure to make
 133 a backup first.  You've been warned!
 134
 135 Removing plugin packages
 136 ========================
 137
 138 To remove an external plugin's package, use ``pip uninstall``. For example::
 139
 140     pip uninstall mediagoblin-licenses
 141
 142 .. Note::
 143
 144    If you're using a virtual environment, make sure to activate the
 145    virtual environment before uninstalling with pip. Otherwise the
 146    plugin may get installed in a different environment.
 147
 148
 149 Upgrading plugins
 150 =================
 151
 152 Core plugins
 153 ------------
 154
 155 Core plugins get upgraded automatically when you upgrade MediaGoblin
 156 because they come with MediaGoblin.
 157
 158
 159 Other plugins
 160 -------------
 161
 162 For plugins that you install with pip, you can upgrade them with pip::
 163
 164     pip install -U <plugin-name>
 165
 166 The ``-U`` tells pip to upgrade the package.
 167
 168
 169 Troubleshooting plugins
 170 =======================
 171
 172 Sometimes plugins just don't work right. When you're having problems
 173 with plugins, think about the following:
 174
 175 1. Check the log files.
 176
 177    Some plugins will log errors to the log files and you can use that
 178    to diagnose the problem.
 179
 180 2. Try running MediaGoblin without that plugin.
 181
 182    It's easy to disable a plugin from MediaGoblin. Add a ``-`` to the
 183    name in your config file.
 184
 185    For example, change::
 186
 187        [[mediagoblin.plugins.flatpagesfile]]
 188
 189    to::
 190
 191        [[-mediagoblin.plugins.flatpagesfile]]
 192
 193    That'll prevent the ``mediagoblin.plugins.flatpagesfile`` plugin from
 194    loading.
 195
 196 3. If it's a core plugin that comes with MediaGoblin, ask us for help!
 197
 198    If it's a plugin you got from somewhere else, ask them for help!