moinsetup

README.txt

44:0aa7a495381b
2011-09-16 Paul Boddie Added support for placing the static resources in a nominated directory even when using normal (non-limited) hosting.
     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).