1 Introduction
2 ------------
3
4 The moinsetup script is a utility separate from MoinMoin which attempts to
5 assist in the configuration and deployment of MoinMoin and extensions. It can
6 automate the installation of MoinMoin according to recommended practices,
7 create and initialise new Wiki instances, install extensions, themes and
8 related resources, and perform certain configuration changes.
9
10 Important Notices
11 -----------------
12
13 Release 0.3 of moinsetup changes the Wiki instance directory hierarchy so that
14 the top-level directory, instead of containing the conf and wikidata
15 directories, contains the Wiki configuration file (unless located elsewhere -
16 see the site_config setting) plus data, underlay and htdocs directories. See
17 the migration section below for details.
18
19 Release 0.3 also changes the moinsetup command syntax to require -m (or
20 --method=) before method names. This fixes a critical ambiguity issue with
21 option processing.
22
23 Usage
24 -----
25
26 Running moinsetup as follows will provide a list of methods available:
27
28 python moinsetup.py
29
30 Before any work can be done by the program, a configuration file needs to be
31 created. See the supplied moinsetup.cfg file in the examples directory which
32 can be modified and used for this purpose.
33
34 An alternative configuration file is specified using the -f option:
35
36 python moinsetup.py -f mywiki.cfg
37
38 Configuration files provide information about the MoinMoin installation and a
39 particular Wiki instance and Web site where the instance is published.
40
41 Migration from moinsetup 0.2
42 ----------------------------
43
44 The Wiki instance directory hierarchy has changed in moinsetup 0.3 as
45 illustrated below:
46
47 wiki (old)
48 conf
49 (wikiconfig.py)
50 data
51 underlay
52 wikidata
53 ... (htdocs)
54
55 wiki (new)
56 (wikiconfig.py)
57 data
58 underlay
59 (htdocs)
60
61 Since the contents of wikidata is generally superfluous, since the files are
62 mostly shared resources, that directory is no longer created and such shared
63 resources are no longer copied into it. The htdocs directory is copied since
64 it can be convenient to maintain a separate collection of static files so that
65 they can be updated with theme-related changes without modifying common system
66 files.
67
68 To migrate old Wiki instance layouts, run the following command:
69
70 python moinsetup.py -m migrate_instance
71
72 Add an optional argument after the method name to run the migration method in
73 test mode:
74
75 python moinsetup.py -m migrate_instance test
76
77 This will just print the actions to be taken when migrating the instance.
78
79 Configuration
80 -------------
81
82 The configuration file has two sections: "installation" and "site". A brief
83 description of the settings is given below.
84
85 Installation settings influence the configuration, installation and
86 customisation of a Wiki and are generally not optional:
87
88 moin_distribution A path to a MoinMoin distribution directory, which can
89 also be a clone of a MoinMoin repository.
90
91 prefix The directory prefix containing lib, bin and share
92 directories where MoinMoin is (or will be) installed.
93 Although this follows the layout of the /usr directory (on
94 Unix-based systems), it is likely that MoinMoin may be
95 installed elsewhere.
96
97 site_packages The location of a directory which is either a Python
98 site-packages directory or something providing a selection
99 of different Python packages. If Python packages are
100 installed outside the 'prefix' area, perhaps due to a
101 distribution-specific mechanism, this setting should be
102 used in addition to the 'prefix' setting. Otherwise, it can
103 be omitted or left blank.
104
105 web_app_dir A directory where the moin.cgi program is (or will be)
106 installed.
107
108 web_static_dir A directory from which static resources are to be served.
109 This directory need only be specified in a limited hosting
110 environment (see below for more details).
111
112 web_site_dir The directory where sites available to the Apache Web
113 server are defined. This directory may just be a place
114 where initial site definitions are written, and after
115 manual editing, such definitions may be copied to the
116 appropriate location. If this directory is left
117 unspecified, a limited hosting environment will be
118 assumed.
119
120 The following Web server settings are optional, but they should probably be
121 investigated and specified:
122
123 web_user The user operating the Web server, typically www-user or
124 apache. This setting is typically used where the
125 filesystem supports ACLs and the setfacl program can be
126 run.
127
128 web_group The group of the user operating the Web server, typically
129 the same as the user. This setting is typically used where
130 the ownership of files has to be modified in order to
131 allow the Web server to access the Wiki programs and
132 files, thus preserving the original ownership of the
133 installed files.
134
135 Except for the common_dir setting, site settings are generally only relevant
136 when configuring and installing a Wiki:
137
138 common_dir The directory in which the Wiki instance being configured
139 or managed resides (or will reside).
140
141 farm_config A specific Wiki farm configuration file for multiple Wiki
142 deployments. This overrides the 'common_dir' setting if
143 used, indicating that a Wiki farm configuration must be
144 edited when configuring a Wiki, and must refer to an
145 actual file, not merely a directory.
146
147 site_config A specific configuration file location for a Wiki deployed
148 within a Wiki farm. This overrides the 'common_dir' setting
149 if used, and must refer to an actual file, not merely a
150 directory.
151
152 url_path The URL path (after the host details) of the Wiki.
153
154 static_url_path The URL path (after the host details) of the Wiki's static
155 resources. This is only required if a limited hosting
156 environment enforces separate "htdocs" and "cgi-bin"
157 directories, and the static resources must be placed in
158 the "htdocs" directory.
159
160 superuser The superuser of the Wiki.
161
162 site_name The name of the Wiki.
163
164 site_identifier An identifier used to refer to the site, typically derived
165 from 'site_name' if left unspecified, and only really of use
166 when an Apache site file needs to be written. In limited
167 hosting environments, this setting has no effect.
168
169 front_page_name The name of the Wiki's front page.
170
171 theme_default The default theme of the Wiki.
172
173 Working with MoinMoin System Installations
174 ------------------------------------------
175
176 Where MoinMoin has already been installed using a package supplied by an
177 operating system distribution (such as Debian, Red Hat, Ubuntu), there is no
178 need to install the software itself. However, it is still necessary to set up
179 Wiki instances. The moinsetup.cfg.debian file in the examples directory could
180 be used as a starting point for configuring Wiki instances on Debian systems.
181
182 Limited Hosting Environments
183 ----------------------------
184
185 Sometimes, the hosting environment in which MoinMoin is to be deployed will be
186 restrictive or "limited", meaning that substantial configuration of the Web
187 server will not be possible for the user installing and configuring MoinMoin.
188 In such environments, users will typically be allowed to install content in
189 preconfigured directories for static and dynamic content. For example:
190
191 /path/to/www/cgi-bin a dynamic content directory, providing CGI scripts
192 /path/to/www/htdocs a static content directory, providing Web pages
193
194 To work in such environments, specify the configuration settings in
195 moinsetup.cfg as follows:
196
197 web_app_dir = /path/to/www/cgi-bin
198 web_static_dir = /path/to/www/htdocs
199 web_site_dir =
200
201 url_path = /mysite/cgi-bin
202 static_url_path = /mysite
203
204 If the web_static_dir setting is left blank, the static resources will be
205 placed alongside the CGI script. Some environments have .cgi files served as
206 CGI scripts and other files served statically; in such cases, static_url_path
207 can also be left blank.
208
209 Inside the directory used to hold static resources, a subdirectory will be
210 created to hold the static content used by MoinMoin.
211
212 See the moinsetup.cfg.sourceforge file in the examples directory for an
213 illustration of how Wiki instances can be configured in a restrictive hosting
214 environment.
215
216 Wiki Farm Environments
217 ----------------------
218
219 MoinMoin supports the notion of a Wiki farm where a single common configuration
220 is overridden by configurations for individual Wiki instances. To work in such
221 environments, specify the configuration settings in moinsetup.cfg as follows:
222
223 farm_config = /path/to/farmconfig.py
224 site_config = /path/to/wikiname.py
225
226 Examples
227 --------
228
229 Some of the more useful invocation methods are described below using examples.
230
231 To set up MoinMoin and a Wiki instance (useful when installing MoinMoin
232 yourself):
233
234 python moinsetup.py -m setup
235
236 To set up only a Wiki instance (useful on a system with MoinMoin installed):
237
238 python moinsetup.py -m setup_wiki
239
240 To set up only a Wiki instance, but using a different configuration file:
241
242 python moinsetup.py -f mywiki.cfg -m setup_wiki
243
244 To change a Wiki configuration setting (for example, the default theme):
245
246 python moinsetup.py -m reconfigure_moin theme_default mercurialwiki
247
248 To install a theme from a directory containing a theme module, css and img
249 directories (for example, MercurialWikiTheme):
250
251 python moinsetup.py -m install_theme /path/to/MercurialWikiTheme/themes/mercurialwiki
252
253 To install an extension package from a directory containing a setup.py script
254 (for example, EventAggregator):
255
256 python moinsetup.py -m install_extension_package /path/to/EventAggregator
257
258 To install actions from a directory containing action modules:
259
260 python moinsetup.py -m install_actions /path/to/EventAggregator/actions
261
262 To install macros from a directory containing macro modules:
263
264 python moinsetup.py -m install_macros /path/to/EventAggregator/macros
265
266 To install theme-related resources for an extension from a directory
267 containing css and img directories:
268
269 python moinsetup.py -m install_theme_resources /path/to/EventAggregator
270
271 To add theme-related resources to existing stylesheets (for example, adding
272 the event-aggregator.css resource to the screen.css stylesheet for all
273 installed themes):
274
275 python moinsetup.py -m edit_theme_stylesheet screen.css event-aggregator.css
276
277 To make a page package containing pages to be added to a Wiki:
278
279 python moinsetup.py -m make_page_package pages_dir pages.zip
280
281 To install a page package in a Wiki:
282
283 python moinsetup.py -m install_page_package pages.zip
284
285 Contact, Copyright and Licence Information
286 ------------------------------------------
287
288 See the following Web page for more information about this work:
289
290 http://moinmo.in/ScriptMarket/moinsetup
291
292 The author can be contacted at the following e-mail address:
293
294 paul@boddie.org.uk
295
296 Copyright and licence information can be found in the docs directory - see
297 docs/COPYING.txt and docs/gpl-3.0.txt for more information.
298
299 Dependencies
300 ------------
301
302 moinsetup has the following basic dependencies:
303
304 Packages Release Information
305 -------- -------------------
306
307 CMDsyntax Tested with 0.91
308 Source: http://www.boddie.org.uk/david/Projects/Python/CMDSyntax/index.html
309
310 New in moinsetup 0.4 (Changes since moinsetup 0.3)
311 --------------------------------------------------
312
313 * Added wikiconfig.py, edit-log and event-log permissions/ownership commands
314 to the postinstall scripts.
315 * Fixed the .htaccess file location for limited hosting environments, using
316 the static resources directory in preference to the application directory.
317 * Added support for separate static URL paths enforced by limited hosting
318 environments.
319 * Added web_user and web_group settings.
320 * Added support for making hierarchical page packages.
321 * Introduced detection of setup.py files when installing plugins.
322
323 New in moinsetup 0.3 (Changes since moinsetup 0.2)
324 --------------------------------------------------
325
326 * Changed the command syntax to require -m (or --method=) before method
327 names; improved the error reporting when settings are missing or
328 inappropriate.
329 * Flattened the Wiki instance hierarchy, putting the configuration, data,
330 underlay and htdocs in the same top-level directory. (See the migration
331 section in the documentation for information on updating the hierarchy.)
332 * Changed the location of MoinMoin 1.9 resources, installing them in the
333 prefix hierarchy and copying only static resources into Wiki instances.
334 * Changed the handling of static resources with MoinMoin 1.9 to serve them
335 separately just as MoinMoin 1.8 does; this makes performance much better
336 when CGI is used under Apache.
337 * Moved the editing of the moin script into the setup method so that no
338 attempt is made to edit system programs.
339 * Made moin_distribution optional so that when MoinMoin is installed from a
340 system package, the non-installation actions can still be performed using
341 shared data typically found in /usr/share/moin.
342 * Added support for Wiki farms, separate library/site-packages directories,
343 and site identifiers (based on site names).
344 * Improved the MoinMoin version detection.
345 * Added an event handler installation action.
346
347 New in moinsetup 0.2 (Changes since moinsetup 0.1)
348 --------------------------------------------------
349
350 * Improved OpenID configuration, supporting MoinMoin 1.9, and added support
351 for other authentication methods.
352 * Added support for ACL-capable filesystems when setting Wiki permissions.
353 It can be more convenient to retain read/write access to the installed
354 files while also granting the Web server user (who need not be in a common
355 group) access to read and modify the files.
356 * Added support for configurations employing a separate static resources
357 directory (such as a typical "htdocs" directory).
358 * Added a parser installation action.
359 * Added support for page attachments in the page-packaging action.
360
361 Release Procedures
362 ------------------
363
364 Update the moinsetup.py __version__ attribute.
365 Change the version number and package filename/directory in the documentation.
366 Update the release notes (see above).
367 Tag, export.
368 Archive, upload.
369 Update the ScriptMarket (see above for the URL).