Annotated README.txt

2013-09-08 Paul Boddie Updated release notes.
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@63 120
The following Web server settings are optional, but they should probably be
paul@63 121
investigated and specified:
paul@63 122
paul@63 123
web_user            The user operating the Web server, typically www-user or
paul@63 124
                    apache. This setting is typically used where the
paul@63 125
                    filesystem supports ACLs and the setfacl program can be
paul@63 126
paul@63 127
paul@63 128
web_group           The group of the user operating the Web server, typically
paul@63 129
                    the same as the user. This setting is typically used where
paul@63 130
                    the ownership of files has to be modified in order to
paul@63 131
                    allow the Web server to access the Wiki programs and
paul@63 132
                    files, thus preserving the original ownership of the
paul@63 133
                    installed files.
paul@63 134
paul@36 135
Except for the common_dir setting, site settings are generally only relevant
paul@36 136
when configuring and installing a Wiki:
paul@27 137
paul@27 138
common_dir          The directory in which the Wiki instance being configured
paul@27 139
                    or managed resides (or will reside).
paul@27 140
paul@43 141
farm_config         A specific Wiki farm configuration file for multiple Wiki
paul@43 142
                    deployments. This overrides the 'common_dir' setting if
paul@43 143
                    used, indicating that a Wiki farm configuration must be
paul@62 144
                    edited when configuring a Wiki, and must refer to an
paul@62 145
                    actual file, not merely a directory.
paul@43 146
paul@43 147
site_config         A specific configuration file location for a Wiki deployed
paul@43 148
                    within a Wiki farm. This overrides the 'common_dir' setting
paul@62 149
                    if used, and must refer to an actual file, not merely a
paul@62 150
paul@43 151
paul@27 152
url_path            The URL path (after the host details) of the Wiki.
paul@43 153
paul@58 154
static_url_path     The URL path (after the host details) of the Wiki's static
paul@58 155
                    resources. This is only required if a limited hosting
paul@58 156
                    environment enforces separate "htdocs" and "cgi-bin"
paul@58 157
                    directories, and the static resources must be placed in
paul@58 158
                    the "htdocs" directory.
paul@58 159
paul@27 160
superuser           The superuser of the Wiki.
paul@43 161
paul@27 162
site_name           The name of the Wiki.
paul@43 163
paul@43 164
site_identifier     An identifier used to refer to the site, typically derived
paul@43 165
                    from 'site_name' if left unspecified, and only really of use
paul@43 166
                    when an Apache site file needs to be written. In limited
paul@43 167
                    hosting environments, this setting has no effect.
paul@43 168
paul@27 169
front_page_name     The name of the Wiki's front page.
paul@43 170
paul@27 171
theme_default       The default theme of the Wiki.
paul@27 172
paul@43 173
Working with MoinMoin System Installations
paul@43 174
paul@43 175
paul@43 176
Where MoinMoin has already been installed using a package supplied by an
paul@43 177
operating system distribution (such as Debian, Red Hat, Ubuntu), there is no
paul@43 178
need to install the software itself. However, it is still necessary to set up
paul@51 179
Wiki instances. The moinsetup.cfg.debian file in the examples directory could
paul@51 180
be used as a starting point for configuring Wiki instances on Debian systems.
paul@43 181
paul@36 182
Limited Hosting Environments
paul@36 183
paul@36 184
paul@36 185
Sometimes, the hosting environment in which MoinMoin is to be deployed will be
paul@36 186
restrictive or "limited", meaning that substantial configuration of the Web
paul@36 187
server will not be possible for the user installing and configuring MoinMoin.
paul@36 188
In such environments, users will typically be allowed to install content in
paul@36 189
preconfigured directories for static and dynamic content. For example:
paul@36 190
paul@36 191
/path/to/www/cgi-bin    a dynamic content directory, providing CGI scripts
paul@36 192
/path/to/www/htdocs     a static content directory, providing Web pages
paul@36 193
paul@36 194
To work in such environments, specify the configuration settings in
paul@36 195
moinsetup.cfg as follows:
paul@36 196
paul@36 197
web_app_dir     = /path/to/www/cgi-bin
paul@36 198
web_static_dir  = /path/to/www/htdocs
paul@36 199
web_site_dir    =
paul@36 200
paul@58 201
url_path        = /mysite/cgi-bin
paul@58 202
static_url_path = /mysite
paul@58 203
paul@43 204
If the web_static_dir setting is left blank, the static resources will be
paul@43 205
placed alongside the CGI script. Some environments have .cgi files served as
paul@58 206
CGI scripts and other files served statically; in such cases, static_url_path
paul@58 207
can also be left blank.
paul@43 208
paul@43 209
Inside the directory used to hold static resources, a subdirectory will be
paul@43 210
created to hold the static content used by MoinMoin.
paul@43 211
paul@60 212
See the moinsetup.cfg.sourceforge file in the examples directory for an
paul@60 213
illustration of how Wiki instances can be configured in a restrictive hosting
paul@60 214
paul@60 215
paul@43 216
Wiki Farm Environments
paul@43 217
paul@43 218
paul@43 219
MoinMoin supports the notion of a Wiki farm where a single common configuration
paul@43 220
is overridden by configurations for individual Wiki instances. To work in such
paul@43 221
environments, specify the configuration settings in moinsetup.cfg as follows:
paul@43 222
paul@43 223
farm_config     = /path/to/
paul@43 224
site_config     = /path/to/
paul@36 225
paul@27 226
paul@27 227
paul@27 228
paul@27 229
Some of the more useful invocation methods are described below using examples.
paul@27 230
paul@43 231
To set up MoinMoin and a Wiki instance (useful when installing MoinMoin
paul@43 232
paul@27 233
paul@43 234
  python -m setup
paul@27 235
paul@43 236
To set up only a Wiki instance (useful on a system with MoinMoin installed):
paul@43 237
paul@43 238
  python -m setup_wiki
paul@27 239
paul@43 240
To set up only a Wiki instance, but using a different configuration file:
paul@43 241
paul@43 242
  python -f mywiki.cfg -m setup_wiki
paul@27 243
paul@36 244
To change a Wiki configuration setting (for example, the default theme):
paul@27 245
paul@43 246
  python -m reconfigure_moin theme_default mercurialwiki
paul@27 247
paul@27 248
To install a theme from a directory containing a theme module, css and img
paul@27 249
directories (for example, MercurialWikiTheme):
paul@27 250
paul@43 251
  python -m install_theme /path/to/MercurialWikiTheme/themes/mercurialwiki
paul@27 252
paul@27 253
To install an extension package from a directory containing a script
paul@27 254
(for example, EventAggregator):
paul@27 255
paul@43 256
  python -m install_extension_package /path/to/EventAggregator
paul@27 257
paul@27 258
To install actions from a directory containing action modules:
paul@27 259
paul@43 260
  python -m install_actions /path/to/EventAggregator/actions
paul@27 261
paul@27 262
To install macros from a directory containing macro modules:
paul@27 263
paul@43 264
  python -m install_macros /path/to/EventAggregator/macros
paul@27 265
paul@27 266
To install theme-related resources for an extension from a directory
paul@27 267
containing css and img directories:
paul@27 268
paul@43 269
  python -m install_theme_resources /path/to/EventAggregator
paul@27 270
paul@27 271
To add theme-related resources to existing stylesheets (for example, adding
paul@27 272
the event-aggregator.css resource to the screen.css stylesheet for all
paul@27 273
installed themes):
paul@27 274
paul@43 275
  python -m edit_theme_stylesheet screen.css event-aggregator.css
paul@27 276
paul@27 277
To make a page package containing pages to be added to a Wiki:
paul@27 278
paul@43 279
  python -m make_page_package pages_dir
paul@27 280
paul@27 281
To install a page package in a Wiki:
paul@27 282
paul@43 283
  python -m install_page_package
paul@27 284
paul@27 285
Contact, Copyright and Licence Information
paul@27 286
paul@27 287
paul@27 288
See the following Web page for more information about this work:
paul@27 289
paul@27 290
paul@27 291
paul@27 292
The author can be contacted at the following e-mail address:
paul@27 293
paul@27 294
paul@27 295
paul@27 296
Copyright and licence information can be found in the docs directory - see
paul@29 297
docs/COPYING.txt and docs/gpl-3.0.txt for more information.
paul@27 298
paul@27 299
paul@27 300
paul@27 301
paul@27 302
moinsetup has the following basic dependencies:
paul@27 303
paul@27 304
Packages                    Release Information
paul@27 305
--------                    -------------------
paul@27 306
paul@27 307
CMDsyntax                   Tested with 0.91
paul@27 308
paul@27 309
paul@58 310
New in moinsetup 0.4 (Changes since moinsetup 0.3)
paul@58 311
paul@58 312
paul@63 313
  * Added, edit-log and event-log permissions/ownership commands
paul@63 314
    to the postinstall scripts.
paul@58 315
  * Fixed the .htaccess file location for limited hosting environments, using
paul@58 316
    the static resources directory in preference to the application directory.
paul@58 317
  * Added support for separate static URL paths enforced by limited hosting
paul@58 318
paul@63 319
  * Added web_user and web_group settings.
paul@65 320
  * Added support for making hierarchical page packages.
paul@65 321
  * Introduced detection of files when installing plugins.
paul@70 322
  * Introduced compilation of plugins upon deployment and more restrictive
paul@70 323
    permissions on files in the plugins directory.
paul@75 324
  * Added workarounds for a mod_rewrite bug where question marks in page names
paul@75 325
    are not correctly interpreted, applicable to .htaccess deployment.
paul@58 326
paul@40 327
New in moinsetup 0.3 (Changes since moinsetup 0.2)
paul@40 328
paul@40 329
paul@43 330
  * Changed the command syntax to require -m (or --method=) before method
paul@43 331
    names; improved the error reporting when settings are missing or
paul@43 332
paul@43 333
  * Flattened the Wiki instance hierarchy, putting the configuration, data,
paul@47 334
    underlay and htdocs in the same top-level directory. (See the migration
paul@47 335
    section in the documentation for information on updating the hierarchy.)
paul@43 336
  * Changed the location of MoinMoin 1.9 resources, installing them in the
paul@43 337
    prefix hierarchy and copying only static resources into Wiki instances.
paul@43 338
  * Changed the handling of static resources with MoinMoin 1.9 to serve them
paul@43 339
    separately just as MoinMoin 1.8 does; this makes performance much better
paul@43 340
    when CGI is used under Apache.
paul@43 341
  * Moved the editing of the moin script into the setup method so that no
paul@43 342
    attempt is made to edit system programs.
paul@43 343
  * Made moin_distribution optional so that when MoinMoin is installed from a
paul@43 344
    system package, the non-installation actions can still be performed using
paul@43 345
    shared data typically found in /usr/share/moin.
paul@43 346
  * Added support for Wiki farms, separate library/site-packages directories,
paul@43 347
    and site identifiers (based on site names).
paul@43 348
  * Improved the MoinMoin version detection.
paul@52 349
  * Added an event handler installation action.
paul@40 350
paul@35 351
New in moinsetup 0.2 (Changes since moinsetup 0.1)
paul@35 352
paul@35 353
paul@35 354
  * Improved OpenID configuration, supporting MoinMoin 1.9, and added support
paul@35 355
    for other authentication methods.
paul@35 356
  * Added support for ACL-capable filesystems when setting Wiki permissions.
paul@35 357
    It can be more convenient to retain read/write access to the installed
paul@35 358
    files while also granting the Web server user (who need not be in a common
paul@35 359
    group) access to read and modify the files.
paul@35 360
  * Added support for configurations employing a separate static resources
paul@35 361
    directory (such as a typical "htdocs" directory).
paul@35 362
  * Added a parser installation action.
paul@35 363
  * Added support for page attachments in the page-packaging action.
paul@35 364
paul@27 365
Release Procedures
paul@27 366
paul@27 367
paul@27 368
Update the __version__ attribute.
paul@27 369
Change the version number and package filename/directory in the documentation.
paul@27 370
Update the release notes (see above).
paul@27 371
Tag, export.
paul@27 372
Archive, upload.
paul@27 373
Update the ScriptMarket (see above for the URL).