Introduction ------------ The moinsetup script is a utility separate from MoinMoin which attempts to assist in the configuration and deployment of MoinMoin and extensions. It can automate the installation of MoinMoin according to recommended practices, create and initialise new Wiki instances, install extensions, themes and related resources, and perform certain configuration changes. Important Notices ----------------- Release 0.3 of moinsetup changes the Wiki instance directory hierarchy so that the top-level directory, instead of containing the conf and wikidata directories, contains the Wiki configuration file (unless located elsewhere - see the site_config setting) plus data, underlay and htdocs directories. See the migration section below for details. Release 0.3 also changes the moinsetup command syntax to require -m (or --method=) before method names. This fixes a critical ambiguity issue with option processing. Usage ----- Running moinsetup as follows will provide a list of methods available: python moinsetup.py Before any work can be done by the program, a configuration file needs to be created. See the supplied moinsetup.cfg file in the examples directory which can be modified and used for this purpose. An alternative configuration file is specified using the -f option: python moinsetup.py -f mywiki.cfg Configuration files provide information about the MoinMoin installation and a particular Wiki instance and Web site where the instance is published. Migration from moinsetup 0.2 ---------------------------- The Wiki instance directory hierarchy has changed in moinsetup 0.3 as illustrated below: wiki (old) conf (wikiconfig.py) data underlay wikidata ... (htdocs) wiki (new) (wikiconfig.py) data underlay (htdocs) Since the contents of wikidata is generally superfluous, since the files are mostly shared resources, that directory is no longer created and such shared resources are no longer copied into it. The htdocs directory is copied since it can be convenient to maintain a separate collection of static files so that they can be updated with theme-related changes without modifying common system files. To migrate old Wiki instance layouts, run the following command: python moinsetup.py -m migrate_instance Add an optional argument after the method name to run the migration method in test mode: python moinsetup.py -m migrate_instance test This will just print the actions to be taken when migrating the instance. Configuration ------------- The configuration file has two sections: "installation" and "site". A brief description of the settings is given below. Installation settings influence the configuration, installation and customisation of a Wiki and are generally not optional: moin_distribution A path to a MoinMoin distribution directory, which can also be a clone of a MoinMoin repository. prefix The directory prefix containing lib, bin and share directories where MoinMoin is (or will be) installed. Although this follows the layout of the /usr directory (on Unix-based systems), it is likely that MoinMoin may be installed elsewhere. site_packages The location of a directory which is either a Python site-packages directory or something providing a selection of different Python packages. If Python packages are installed outside the 'prefix' area, perhaps due to a distribution-specific mechanism, this setting should be used in addition to the 'prefix' setting. Otherwise, it can be omitted or left blank. web_app_dir A directory where the moin.cgi program is (or will be) installed. web_static_dir A directory from which static resources are to be served. This directory need only be specified in a limited hosting environment (see below for more details). web_site_dir The directory where sites available to the Apache Web server are defined. This directory may just be a place where initial site definitions are written, and after manual editing, such definitions may be copied to the appropriate location. If this directory is left unspecified, a limited hosting environment will be assumed. The following Web server settings are optional, but they should probably be investigated and specified: web_user The user operating the Web server, typically www-user or apache. This setting is typically used where the filesystem supports ACLs and the setfacl program can be run. web_group The group of the user operating the Web server, typically the same as the user. This setting is typically used where the ownership of files has to be modified in order to allow the Web server to access the Wiki programs and files, thus preserving the original ownership of the installed files. Except for the common_dir setting, site settings are generally only relevant when configuring and installing a Wiki: common_dir The directory in which the Wiki instance being configured or managed resides (or will reside). farm_config A specific Wiki farm configuration file for multiple Wiki deployments. This overrides the 'common_dir' setting if used, indicating that a Wiki farm configuration must be edited when configuring a Wiki, and must refer to an actual file, not merely a directory. site_config A specific configuration file location for a Wiki deployed within a Wiki farm. This overrides the 'common_dir' setting if used, and must refer to an actual file, not merely a directory. url_path The URL path (after the host details) of the Wiki. static_url_path The URL path (after the host details) of the Wiki's static resources. This is only required if a limited hosting environment enforces separate "htdocs" and "cgi-bin" directories, and the static resources must be placed in the "htdocs" directory. superuser The superuser of the Wiki. site_name The name of the Wiki. site_identifier An identifier used to refer to the site, typically derived from 'site_name' if left unspecified, and only really of use when an Apache site file needs to be written. In limited hosting environments, this setting has no effect. front_page_name The name of the Wiki's front page. theme_default The default theme of the Wiki. Working with MoinMoin System Installations ------------------------------------------ Where MoinMoin has already been installed using a package supplied by an operating system distribution (such as Debian, Red Hat, Ubuntu), there is no need to install the software itself. However, it is still necessary to set up Wiki instances. The moinsetup.cfg.debian file in the examples directory could be used as a starting point for configuring Wiki instances on Debian systems. Limited Hosting Environments ---------------------------- Sometimes, the hosting environment in which MoinMoin is to be deployed will be restrictive or "limited", meaning that substantial configuration of the Web server will not be possible for the user installing and configuring MoinMoin. In such environments, users will typically be allowed to install content in preconfigured directories for static and dynamic content. For example: /path/to/www/cgi-bin a dynamic content directory, providing CGI scripts /path/to/www/htdocs a static content directory, providing Web pages To work in such environments, specify the configuration settings in moinsetup.cfg as follows: web_app_dir = /path/to/www/cgi-bin web_static_dir = /path/to/www/htdocs web_site_dir = url_path = /mysite/cgi-bin static_url_path = /mysite If the web_static_dir setting is left blank, the static resources will be placed alongside the CGI script. Some environments have .cgi files served as CGI scripts and other files served statically; in such cases, static_url_path can also be left blank. Inside the directory used to hold static resources, a subdirectory will be created to hold the static content used by MoinMoin. See the moinsetup.cfg.sourceforge file in the examples directory for an illustration of how Wiki instances can be configured in a restrictive hosting environment. Wiki Farm Environments ---------------------- MoinMoin supports the notion of a Wiki farm where a single common configuration is overridden by configurations for individual Wiki instances. To work in such environments, specify the configuration settings in moinsetup.cfg as follows: farm_config = /path/to/farmconfig.py site_config = /path/to/wikiname.py Examples -------- Some of the more useful invocation methods are described below using examples. To set up MoinMoin and a Wiki instance (useful when installing MoinMoin yourself): python moinsetup.py -m setup To set up only a Wiki instance (useful on a system with MoinMoin installed): python moinsetup.py -m setup_wiki To set up only a Wiki instance, but using a different configuration file: python moinsetup.py -f mywiki.cfg -m setup_wiki To change a Wiki configuration setting (for example, the default theme): python moinsetup.py -m reconfigure_moin theme_default mercurialwiki To install a theme from a directory containing a theme module, css and img directories (for example, MercurialWikiTheme): python moinsetup.py -m install_theme /path/to/MercurialWikiTheme/themes/mercurialwiki To install an extension package from a directory containing a setup.py script (for example, EventAggregator): python moinsetup.py -m install_extension_package /path/to/EventAggregator To install actions from a directory containing action modules: python moinsetup.py -m install_actions /path/to/EventAggregator/actions To install macros from a directory containing macro modules: python moinsetup.py -m install_macros /path/to/EventAggregator/macros To install theme-related resources for an extension from a directory containing css and img directories: python moinsetup.py -m install_theme_resources /path/to/EventAggregator To add theme-related resources to existing stylesheets (for example, adding the event-aggregator.css resource to the screen.css stylesheet for all installed themes): python moinsetup.py -m edit_theme_stylesheet screen.css event-aggregator.css To make a page package containing pages to be added to a Wiki: python moinsetup.py -m make_page_package pages_dir pages.zip To install a page package in a Wiki: python moinsetup.py -m install_page_package pages.zip Contact, Copyright and Licence Information ------------------------------------------ See the following Web page for more information about this work: http://moinmo.in/ScriptMarket/moinsetup The author can be contacted at the following e-mail address: paul@boddie.org.uk Copyright and licence information can be found in the docs directory - see docs/COPYING.txt and docs/gpl-3.0.txt for more information. Dependencies ------------ moinsetup has the following basic dependencies: Packages Release Information -------- ------------------- CMDsyntax Tested with 0.91 Source: http://www.boddie.org.uk/david/Projects/Python/CMDSyntax/index.html New in moinsetup 0.4 (Changes since moinsetup 0.3) -------------------------------------------------- * Added wikiconfig.py, edit-log and event-log permissions/ownership commands to the postinstall scripts. * Fixed the .htaccess file location for limited hosting environments, using the static resources directory in preference to the application directory. * Added support for separate static URL paths enforced by limited hosting environments. * Added web_user and web_group settings. * Added support for making hierarchical page packages. * Introduced detection of setup.py files when installing plugins. * Introduced compilation of plugins upon deployment and more restrictive permissions on files in the plugins directory. New in moinsetup 0.3 (Changes since moinsetup 0.2) -------------------------------------------------- * Changed the command syntax to require -m (or --method=) before method names; improved the error reporting when settings are missing or inappropriate. * Flattened the Wiki instance hierarchy, putting the configuration, data, underlay and htdocs in the same top-level directory. (See the migration section in the documentation for information on updating the hierarchy.) * Changed the location of MoinMoin 1.9 resources, installing them in the prefix hierarchy and copying only static resources into Wiki instances. * Changed the handling of static resources with MoinMoin 1.9 to serve them separately just as MoinMoin 1.8 does; this makes performance much better when CGI is used under Apache. * Moved the editing of the moin script into the setup method so that no attempt is made to edit system programs. * Made moin_distribution optional so that when MoinMoin is installed from a system package, the non-installation actions can still be performed using shared data typically found in /usr/share/moin. * Added support for Wiki farms, separate library/site-packages directories, and site identifiers (based on site names). * Improved the MoinMoin version detection. * Added an event handler installation action. New in moinsetup 0.2 (Changes since moinsetup 0.1) -------------------------------------------------- * Improved OpenID configuration, supporting MoinMoin 1.9, and added support for other authentication methods. * Added support for ACL-capable filesystems when setting Wiki permissions. It can be more convenient to retain read/write access to the installed files while also granting the Web server user (who need not be in a common group) access to read and modify the files. * Added support for configurations employing a separate static resources directory (such as a typical "htdocs" directory). * Added a parser installation action. * Added support for page attachments in the page-packaging action. Release Procedures ------------------ Update the moinsetup.py __version__ attribute. Change the version number and package filename/directory in the documentation. Update the release notes (see above). Tag, export. Archive, upload. Update the ScriptMarket (see above for the URL).