moinsetup

Annotated README.txt

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