Commit | Line | Data |
---|---|---|
29b6f917 WKG |
1 | ========= |
2 | Plugins | |
3 | ========= | |
4 | ||
355fd677 WKG |
5 | GNU MediaGoblin supports plugins that allow you to augment MediaGoblin's |
6 | behavior. | |
29b6f917 WKG |
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 | |
355fd677 WKG |
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 | ||
2530ef7a | 24 | .. todo: how do you find plugins on the internet? |
29b6f917 WKG |
25 | |
26 | ||
27 | Installing plugins | |
28 | ================== | |
29 | ||
355fd677 WKG |
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 | ------------- | |
29b6f917 | 40 | |
355fd677 WKG |
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:: | |
29b6f917 WKG |
43 | |
44 | pip install <plugin-name> | |
45 | ||
46 | For example, if we wanted to install the plugin named | |
7989cd6e SS |
47 | "mediagoblin-licenses" (which allows you to customize the licenses you |
48 | offer for your media), we would do:: | |
29b6f917 | 49 | |
7989cd6e | 50 | pip install mediagoblin-licenses |
29b6f917 | 51 | |
464a5d7f | 52 | .. note:: |
29b6f917 WKG |
53 | |
54 | If you're using a virtual environment, make sure to activate the | |
7989cd6e SS |
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 | |
464a5d7f | 58 | python (and thus pip) is python 3 (e.g. in Ubuntu and derivatives). |
29b6f917 WKG |
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 | ||
7989cd6e SS |
65 | For example, say the "mediagoblin-licenses" plugin has the Python |
66 | package path ``mediagoblin_licenses``, then you would add ``mediagoblin_licenses`` to | |
29b6f917 WKG |
67 | the ``plugins`` section as a subsection:: |
68 | ||
69 | [plugins] | |
70 | ||
7989cd6e SS |
71 | [[mediagoblin_licenses]] |
72 | license_01=abbrev1, name1, http://url1 | |
73 | license_02=abbrev2, name1, http://url2 | |
29b6f917 WKG |
74 | |
75 | ||
76 | Configuring plugins | |
77 | =================== | |
78 | ||
355fd677 WKG |
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. | |
29b6f917 WKG |
82 | |
83 | Example 1: Core MediaGoblin plugin | |
84 | ||
85 | If you wanted to use the core MediaGoblin flatpages plugin, the module | |
7a690a5a CAW |
86 | for that is ``mediagoblin.plugins.flatpagesfile`` and you would add |
87 | that to your ``.ini`` file like this:: | |
29b6f917 WKG |
88 | |
89 | [plugins] | |
90 | ||
7a690a5a CAW |
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`) | |
29b6f917 WKG |
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 | ||
cca25b6f | 113 | Once you've set up your plugin, you should be sure to update the |
9650aa39 | 114 | database to accommodate the new plugins:: |
29b6f917 | 115 | |
cca25b6f | 116 | ./bin/gmg dbupdate |
29b6f917 | 117 | |
cca25b6f CAW |
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 | |
9650aa39 | 124 | produce better tooling to accommodate this. In short, you will need to |
cca25b6f CAW |
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:: | |
29b6f917 | 139 | |
7989cd6e | 140 | pip uninstall mediagoblin-licenses |
29b6f917 WKG |
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. | |
355fd677 WKG |
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. | |
05d8f314 WKG |
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 | ||
3a438f5e | 187 | [[mediagoblin.plugins.flatpagesfile]] |
05d8f314 WKG |
188 | |
189 | to:: | |
190 | ||
3a438f5e | 191 | [[-mediagoblin.plugins.flatpagesfile]] |
05d8f314 | 192 | |
3a438f5e | 193 | That'll prevent the ``mediagoblin.plugins.flatpagesfile`` plugin from |
05d8f314 WKG |
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! |