| 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! |