Annotated README.txt

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