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