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