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