moinsetup

README.txt

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