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 moin_data A path to the MoinMoin shared data, which may be installed
34 from a system package in a directory such as
35 /usr/share/moin.
36
37 prefix The directory prefix containing lib, bin and share
38 directories where MoinMoin is (or will be) installed.
39 Although this follows the layout of the /usr directory (on
40 Unix-based systems), it is likely that MoinMoin may be
41 installed elsewhere
42
43 web_app_dir A directory where the moin.cgi program is (or will be)
44 installed.
45
46 web_static_dir A directory from which static resources are to be served.
47 This directory need only be specified in a limited hosting
48 environment (see below for more details).
49
50 web_site_dir The directory where sites available to the Apache Web
51 server are defined. This directory may just be a place
52 where initial site definitions are written, and after
53 manual editing, such definitions may be copied to the
54 appropriate location. If this directory is left
55 unspecified, a limited hosting environment will be
56 assumed.
57
58 Except for the common_dir setting, site settings are generally only relevant
59 when configuring and installing a Wiki:
60
61 common_dir The directory in which the Wiki instance being configured
62 or managed resides (or will reside).
63
64 url_path The URL path (after the host details) of the Wiki.
65 superuser The superuser of the Wiki.
66 site_name The name of the Wiki.
67 front_page_name The name of the Wiki's front page.
68 theme_default The default theme of the Wiki.
69
70 Limited Hosting Environments
71 ----------------------------
72
73 Sometimes, the hosting environment in which MoinMoin is to be deployed will be
74 restrictive or "limited", meaning that substantial configuration of the Web
75 server will not be possible for the user installing and configuring MoinMoin.
76 In such environments, users will typically be allowed to install content in
77 preconfigured directories for static and dynamic content. For example:
78
79 /path/to/www/cgi-bin a dynamic content directory, providing CGI scripts
80 /path/to/www/htdocs a static content directory, providing Web pages
81
82 To work in such environments, specify the configuration settings in
83 moinsetup.cfg as follows:
84
85 web_app_dir = /path/to/www/cgi-bin
86 web_static_dir = /path/to/www/htdocs
87 web_site_dir =
88
89 Inside the static resources directory, a subdirectory will be created to hold
90 any static content used by MoinMoin.
91
92 Examples
93 --------
94
95 Some of the more useful invocation methods are described below using examples.
96
97 To set up MoinMoin and a Wiki instance:
98
99 python moinsetup.py setup
100
101 To only set up a Wiki instance using a different configuration file:
102
103 python moinsetup.py -f new_wiki.cfg setup_wiki
104
105 To change a Wiki configuration setting (for example, the default theme):
106
107 python moinsetup.py reconfigure_moin theme_default mercurialwiki
108
109 To install a theme from a directory containing a theme module, css and img
110 directories (for example, MercurialWikiTheme):
111
112 python moinsetup.py install_theme /path/to/MercurialWikiTheme/themes/mercurialwiki
113
114 To install an extension package from a directory containing a setup.py script
115 (for example, EventAggregator):
116
117 python moinsetup.py install_extension_package /path/to/EventAggregator
118
119 To install actions from a directory containing action modules:
120
121 python moinsetup.py install_actions /path/to/EventAggregator/actions
122
123 To install macros from a directory containing macro modules:
124
125 python moinsetup.py install_macros /path/to/EventAggregator/macros
126
127 To install theme-related resources for an extension from a directory
128 containing css and img directories:
129
130 python moinsetup.py install_theme_resources /path/to/EventAggregator
131
132 To add theme-related resources to existing stylesheets (for example, adding
133 the event-aggregator.css resource to the screen.css stylesheet for all
134 installed themes):
135
136 python moinsetup.py edit_theme_stylesheet screen.css event-aggregator.css
137
138 To make a page package containing pages to be added to a Wiki:
139
140 python moinsetup.py make_page_package pages_dir pages.zip
141
142 To install a page package in a Wiki:
143
144 python moinsetup.py install_page_package pages.zip
145
146 Contact, Copyright and Licence Information
147 ------------------------------------------
148
149 See the following Web page for more information about this work:
150
151 http://moinmo.in/ScriptMarket/moinsetup
152
153 The author can be contacted at the following e-mail address:
154
155 paul@boddie.org.uk
156
157 Copyright and licence information can be found in the docs directory - see
158 docs/COPYING.txt and docs/gpl-3.0.txt for more information.
159
160 Dependencies
161 ------------
162
163 moinsetup has the following basic dependencies:
164
165 Packages Release Information
166 -------- -------------------
167
168 CMDsyntax Tested with 0.91
169 Source: http://www.boddie.org.uk/david/Projects/Python/CMDSyntax/index.html
170
171 New in moinsetup 0.3 (Changes since moinsetup 0.2)
172 --------------------------------------------------
173
174 * Added a moin_data setting and made moin_distribution optional so that when
175 MoinMoin is installed from a system package, the non-installation actions
176 can still be performed.
177
178 New in moinsetup 0.2 (Changes since moinsetup 0.1)
179 --------------------------------------------------
180
181 * Improved OpenID configuration, supporting MoinMoin 1.9, and added support
182 for other authentication methods.
183 * Added support for ACL-capable filesystems when setting Wiki permissions.
184 It can be more convenient to retain read/write access to the installed
185 files while also granting the Web server user (who need not be in a common
186 group) access to read and modify the files.
187 * Added support for configurations employing a separate static resources
188 directory (such as a typical "htdocs" directory).
189 * Added a parser installation action.
190 * Added support for page attachments in the page-packaging action.
191
192 Release Procedures
193 ------------------
194
195 Update the moinsetup.py __version__ attribute.
196 Change the version number and package filename/directory in the documentation.
197 Update the release notes (see above).
198 Tag, export.
199 Archive, upload.
200 Update the ScriptMarket (see above for the URL).
