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 for an example file which can
32 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), and only for
111 MoinMoin 1.8.
112
113 web_site_dir The directory where sites available to the Apache Web
114 server are defined. This directory may just be a place
115 where initial site definitions are written, and after
116 manual editing, such definitions may be copied to the
117 appropriate location. If this directory is left
118 unspecified, a limited hosting environment will be
119 assumed.
120
121 Except for the common_dir setting, site settings are generally only relevant
122 when configuring and installing a Wiki:
123
124 common_dir The directory in which the Wiki instance being configured
125 or managed resides (or will reside).
126
127 farm_config A specific Wiki farm configuration file for multiple Wiki
128 deployments. This overrides the 'common_dir' setting if
129 used, indicating that a Wiki farm configuration must be
130 edited when configuring a Wiki.
131
132 site_config A specific configuration file location for a Wiki deployed
133 within a Wiki farm. This overrides the 'common_dir' setting
134 if used.
135
136 url_path The URL path (after the host details) of the Wiki.
137
138 superuser The superuser of the Wiki.
139
140 site_name The name of the Wiki.
141
142 site_identifier An identifier used to refer to the site, typically derived
143 from 'site_name' if left unspecified, and only really of use
144 when an Apache site file needs to be written. In limited
145 hosting environments, this setting has no effect.
146
147 front_page_name The name of the Wiki's front page.
148
149 theme_default The default theme of the Wiki.
150
151 Working with MoinMoin System Installations
152 ------------------------------------------
153
154 Where MoinMoin has already been installed using a package supplied by an
155 operating system distribution (such as Debian, Red Hat, Ubuntu), there is no
156 need to install the software itself. However, it is still necessary to set up
157 Wiki instances. The moinsetup.cfg.debian file in the examples directory could
158 be used as a starting point for configuring Wiki instances on Debian systems.
159
160 Limited Hosting Environments
161 ----------------------------
162
163 Sometimes, the hosting environment in which MoinMoin is to be deployed will be
164 restrictive or "limited", meaning that substantial configuration of the Web
165 server will not be possible for the user installing and configuring MoinMoin.
166 In such environments, users will typically be allowed to install content in
167 preconfigured directories for static and dynamic content. For example:
168
169 /path/to/www/cgi-bin a dynamic content directory, providing CGI scripts
170 /path/to/www/htdocs a static content directory, providing Web pages
171
172 To work in such environments, specify the configuration settings in
173 moinsetup.cfg as follows:
174
175 web_app_dir = /path/to/www/cgi-bin
176 web_static_dir = /path/to/www/htdocs
177 web_site_dir =
178
179 If the web_static_dir setting is left blank, the static resources will be
180 placed alongside the CGI script. Some environments have .cgi files served as
181 CGI scripts and other files served statically.
182
183 Inside the directory used to hold static resources, a subdirectory will be
184 created to hold the static content used by MoinMoin.
185
186 Wiki Farm Environments
187 ----------------------
188
189 MoinMoin supports the notion of a Wiki farm where a single common configuration
190 is overridden by configurations for individual Wiki instances. To work in such
191 environments, specify the configuration settings in moinsetup.cfg as follows:
192
193 farm_config = /path/to/farmconfig.py
194 site_config = /path/to/wikiname.py
195
196 Examples
197 --------
198
199 Some of the more useful invocation methods are described below using examples.
200
201 To set up MoinMoin and a Wiki instance (useful when installing MoinMoin
202 yourself):
203
204 python moinsetup.py -m setup
205
206 To set up only a Wiki instance (useful on a system with MoinMoin installed):
207
208 python moinsetup.py -m setup_wiki
209
210 To set up only a Wiki instance, but using a different configuration file:
211
212 python moinsetup.py -f mywiki.cfg -m setup_wiki
213
214 To change a Wiki configuration setting (for example, the default theme):
215
216 python moinsetup.py -m reconfigure_moin theme_default mercurialwiki
217
218 To install a theme from a directory containing a theme module, css and img
219 directories (for example, MercurialWikiTheme):
220
221 python moinsetup.py -m install_theme /path/to/MercurialWikiTheme/themes/mercurialwiki
222
223 To install an extension package from a directory containing a setup.py script
224 (for example, EventAggregator):
225
226 python moinsetup.py -m install_extension_package /path/to/EventAggregator
227
228 To install actions from a directory containing action modules:
229
230 python moinsetup.py -m install_actions /path/to/EventAggregator/actions
231
232 To install macros from a directory containing macro modules:
233
234 python moinsetup.py -m install_macros /path/to/EventAggregator/macros
235
236 To install theme-related resources for an extension from a directory
237 containing css and img directories:
238
239 python moinsetup.py -m install_theme_resources /path/to/EventAggregator
240
241 To add theme-related resources to existing stylesheets (for example, adding
242 the event-aggregator.css resource to the screen.css stylesheet for all
243 installed themes):
244
245 python moinsetup.py -m edit_theme_stylesheet screen.css event-aggregator.css
246
247 To make a page package containing pages to be added to a Wiki:
248
249 python moinsetup.py -m make_page_package pages_dir pages.zip
250
251 To install a page package in a Wiki:
252
253 python moinsetup.py -m install_page_package pages.zip
254
255 Contact, Copyright and Licence Information
256 ------------------------------------------
257
258 See the following Web page for more information about this work:
259
260 http://moinmo.in/ScriptMarket/moinsetup
261
262 The author can be contacted at the following e-mail address:
263
264 paul@boddie.org.uk
265
266 Copyright and licence information can be found in the docs directory - see
267 docs/COPYING.txt and docs/gpl-3.0.txt for more information.
268
269 Dependencies
270 ------------
271
272 moinsetup has the following basic dependencies:
273
274 Packages Release Information
275 -------- -------------------
276
277 CMDsyntax Tested with 0.91
278 Source: http://www.boddie.org.uk/david/Projects/Python/CMDSyntax/index.html
279
280 New in moinsetup 0.3 (Changes since moinsetup 0.2)
281 --------------------------------------------------
282
283 * Changed the command syntax to require -m (or --method=) before method
284 names; improved the error reporting when settings are missing or
285 inappropriate.
286 * Flattened the Wiki instance hierarchy, putting the configuration, data,
287 underlay and htdocs in the same top-level directory. (See the migration
288 section in the documentation for information on updating the hierarchy.)
289 * Changed the location of MoinMoin 1.9 resources, installing them in the
290 prefix hierarchy and copying only static resources into Wiki instances.
291 * Changed the handling of static resources with MoinMoin 1.9 to serve them
292 separately just as MoinMoin 1.8 does; this makes performance much better
293 when CGI is used under Apache.
294 * Moved the editing of the moin script into the setup method so that no
295 attempt is made to edit system programs.
296 * Made moin_distribution optional so that when MoinMoin is installed from a
297 system package, the non-installation actions can still be performed using
298 shared data typically found in /usr/share/moin.
299 * Added support for Wiki farms, separate library/site-packages directories,
300 and site identifiers (based on site names).
301 * Improved the MoinMoin version detection.
302 * Added an event handler installation action.
303
304 New in moinsetup 0.2 (Changes since moinsetup 0.1)
305 --------------------------------------------------
306
307 * Improved OpenID configuration, supporting MoinMoin 1.9, and added support
308 for other authentication methods.
309 * Added support for ACL-capable filesystems when setting Wiki permissions.
310 It can be more convenient to retain read/write access to the installed
311 files while also granting the Web server user (who need not be in a common
312 group) access to read and modify the files.
313 * Added support for configurations employing a separate static resources
314 directory (such as a typical "htdocs" directory).
315 * Added a parser installation action.
316 * Added support for page attachments in the page-packaging action.
317
318 Release Procedures
319 ------------------
320
321 Update the moinsetup.py __version__ attribute.
322 Change the version number and package filename/directory in the documentation.
323 Update the release notes (see above).
324 Tag, export.
325 Archive, upload.
326 Update the ScriptMarket (see above for the URL).