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@43 | 37 | installed elsewhere.
|
paul@43 | 38 |
|
paul@43 | 39 | site_packages The location of a directory which is either a Python
|
paul@43 | 40 | site-packages directory or something providing a selection
|
paul@43 | 41 | of different Python packages. If Python packages are
|
paul@43 | 42 | installed outside the 'prefix' area, perhaps due to a
|
paul@43 | 43 | distribution-specific mechanism, this setting should be
|
paul@43 | 44 | used in addition to the 'prefix' setting. Otherwise, it can
|
paul@43 | 45 | be omitted or left blank.
|
paul@27 | 46 |
|
paul@27 | 47 | web_app_dir A directory where the moin.cgi program is (or will be)
|
paul@27 | 48 | installed.
|
paul@27 | 49 |
|
paul@36 | 50 | web_static_dir A directory from which static resources are to be served.
|
paul@36 | 51 | This directory need only be specified in a limited hosting
|
paul@43 | 52 | environment (see below for more details), and only for
|
paul@43 | 53 | MoinMoin 1.8.
|
paul@36 | 54 |
|
paul@27 | 55 | web_site_dir The directory where sites available to the Apache Web
|
paul@27 | 56 | server are defined. This directory may just be a place
|
paul@27 | 57 | where initial site definitions are written, and after
|
paul@27 | 58 | manual editing, such definitions may be copied to the
|
paul@36 | 59 | appropriate location. If this directory is left
|
paul@36 | 60 | unspecified, a limited hosting environment will be
|
paul@36 | 61 | assumed.
|
paul@36 | 62 |
|
paul@36 | 63 | Except for the common_dir setting, site settings are generally only relevant
|
paul@36 | 64 | when configuring and installing a Wiki:
|
paul@27 | 65 |
|
paul@27 | 66 | common_dir The directory in which the Wiki instance being configured
|
paul@27 | 67 | or managed resides (or will reside).
|
paul@27 | 68 |
|
paul@43 | 69 | farm_config A specific Wiki farm configuration file for multiple Wiki
|
paul@43 | 70 | deployments. This overrides the 'common_dir' setting if
|
paul@43 | 71 | used, indicating that a Wiki farm configuration must be
|
paul@43 | 72 | edited when configuring a Wiki.
|
paul@43 | 73 |
|
paul@43 | 74 | site_config A specific configuration file location for a Wiki deployed
|
paul@43 | 75 | within a Wiki farm. This overrides the 'common_dir' setting
|
paul@43 | 76 | if used.
|
paul@43 | 77 |
|
paul@27 | 78 | url_path The URL path (after the host details) of the Wiki.
|
paul@43 | 79 |
|
paul@27 | 80 | superuser The superuser of the Wiki.
|
paul@43 | 81 |
|
paul@27 | 82 | site_name The name of the Wiki.
|
paul@43 | 83 |
|
paul@43 | 84 | site_identifier An identifier used to refer to the site, typically derived
|
paul@43 | 85 | from 'site_name' if left unspecified, and only really of use
|
paul@43 | 86 | when an Apache site file needs to be written. In limited
|
paul@43 | 87 | hosting environments, this setting has no effect.
|
paul@43 | 88 |
|
paul@27 | 89 | front_page_name The name of the Wiki's front page.
|
paul@43 | 90 |
|
paul@27 | 91 | theme_default The default theme of the Wiki.
|
paul@27 | 92 |
|
paul@43 | 93 | Working with MoinMoin System Installations
|
paul@43 | 94 | ------------------------------------------
|
paul@43 | 95 |
|
paul@43 | 96 | Where MoinMoin has already been installed using a package supplied by an
|
paul@43 | 97 | operating system distribution (such as Debian, Red Hat, Ubuntu), there is no
|
paul@43 | 98 | need to install the software itself. However, it is still necessary to set up
|
paul@43 | 99 | Wiki instances.
|
paul@43 | 100 |
|
paul@36 | 101 | Limited Hosting Environments
|
paul@36 | 102 | ----------------------------
|
paul@36 | 103 |
|
paul@36 | 104 | Sometimes, the hosting environment in which MoinMoin is to be deployed will be
|
paul@36 | 105 | restrictive or "limited", meaning that substantial configuration of the Web
|
paul@36 | 106 | server will not be possible for the user installing and configuring MoinMoin.
|
paul@36 | 107 | In such environments, users will typically be allowed to install content in
|
paul@36 | 108 | preconfigured directories for static and dynamic content. For example:
|
paul@36 | 109 |
|
paul@36 | 110 | /path/to/www/cgi-bin a dynamic content directory, providing CGI scripts
|
paul@36 | 111 | /path/to/www/htdocs a static content directory, providing Web pages
|
paul@36 | 112 |
|
paul@36 | 113 | To work in such environments, specify the configuration settings in
|
paul@36 | 114 | moinsetup.cfg as follows:
|
paul@36 | 115 |
|
paul@36 | 116 | web_app_dir = /path/to/www/cgi-bin
|
paul@36 | 117 | web_static_dir = /path/to/www/htdocs
|
paul@36 | 118 | web_site_dir =
|
paul@36 | 119 |
|
paul@43 | 120 | If the web_static_dir setting is left blank, the static resources will be
|
paul@43 | 121 | placed alongside the CGI script. Some environments have .cgi files served as
|
paul@43 | 122 | CGI scripts and other files served statically.
|
paul@43 | 123 |
|
paul@43 | 124 | Inside the directory used to hold static resources, a subdirectory will be
|
paul@43 | 125 | created to hold the static content used by MoinMoin.
|
paul@43 | 126 |
|
paul@43 | 127 | Wiki Farm Environments
|
paul@43 | 128 | ----------------------
|
paul@43 | 129 |
|
paul@43 | 130 | MoinMoin supports the notion of a Wiki farm where a single common configuration
|
paul@43 | 131 | is overridden by configurations for individual Wiki instances. To work in such
|
paul@43 | 132 | environments, specify the configuration settings in moinsetup.cfg as follows:
|
paul@43 | 133 |
|
paul@43 | 134 | farm_config = /path/to/farmconfig.py
|
paul@43 | 135 | site_config = /path/to/wikiname.py
|
paul@36 | 136 |
|
paul@27 | 137 | Examples
|
paul@27 | 138 | --------
|
paul@27 | 139 |
|
paul@27 | 140 | Some of the more useful invocation methods are described below using examples.
|
paul@27 | 141 |
|
paul@43 | 142 | To set up MoinMoin and a Wiki instance (useful when installing MoinMoin
|
paul@43 | 143 | yourself):
|
paul@27 | 144 |
|
paul@43 | 145 | python moinsetup.py -m setup
|
paul@27 | 146 |
|
paul@43 | 147 | To set up only a Wiki instance (useful on a system with MoinMoin installed):
|
paul@43 | 148 |
|
paul@43 | 149 | python moinsetup.py -m setup_wiki
|
paul@27 | 150 |
|
paul@43 | 151 | To set up only a Wiki instance, but using a different configuration file:
|
paul@43 | 152 |
|
paul@43 | 153 | python moinsetup.py -f mywiki.cfg -m setup_wiki
|
paul@27 | 154 |
|
paul@36 | 155 | To change a Wiki configuration setting (for example, the default theme):
|
paul@27 | 156 |
|
paul@43 | 157 | python moinsetup.py -m reconfigure_moin theme_default mercurialwiki
|
paul@27 | 158 |
|
paul@27 | 159 | To install a theme from a directory containing a theme module, css and img
|
paul@27 | 160 | directories (for example, MercurialWikiTheme):
|
paul@27 | 161 |
|
paul@43 | 162 | python moinsetup.py -m install_theme /path/to/MercurialWikiTheme/themes/mercurialwiki
|
paul@27 | 163 |
|
paul@27 | 164 | To install an extension package from a directory containing a setup.py script
|
paul@27 | 165 | (for example, EventAggregator):
|
paul@27 | 166 |
|
paul@43 | 167 | python moinsetup.py -m install_extension_package /path/to/EventAggregator
|
paul@27 | 168 |
|
paul@27 | 169 | To install actions from a directory containing action modules:
|
paul@27 | 170 |
|
paul@43 | 171 | python moinsetup.py -m install_actions /path/to/EventAggregator/actions
|
paul@27 | 172 |
|
paul@27 | 173 | To install macros from a directory containing macro modules:
|
paul@27 | 174 |
|
paul@43 | 175 | python moinsetup.py -m install_macros /path/to/EventAggregator/macros
|
paul@27 | 176 |
|
paul@27 | 177 | To install theme-related resources for an extension from a directory
|
paul@27 | 178 | containing css and img directories:
|
paul@27 | 179 |
|
paul@43 | 180 | python moinsetup.py -m install_theme_resources /path/to/EventAggregator
|
paul@27 | 181 |
|
paul@27 | 182 | To add theme-related resources to existing stylesheets (for example, adding
|
paul@27 | 183 | the event-aggregator.css resource to the screen.css stylesheet for all
|
paul@27 | 184 | installed themes):
|
paul@27 | 185 |
|
paul@43 | 186 | python moinsetup.py -m edit_theme_stylesheet screen.css event-aggregator.css
|
paul@27 | 187 |
|
paul@27 | 188 | To make a page package containing pages to be added to a Wiki:
|
paul@27 | 189 |
|
paul@43 | 190 | python moinsetup.py -m make_page_package pages_dir pages.zip
|
paul@27 | 191 |
|
paul@27 | 192 | To install a page package in a Wiki:
|
paul@27 | 193 |
|
paul@43 | 194 | python moinsetup.py -m install_page_package pages.zip
|
paul@27 | 195 |
|
paul@27 | 196 | Contact, Copyright and Licence Information
|
paul@27 | 197 | ------------------------------------------
|
paul@27 | 198 |
|
paul@27 | 199 | See the following Web page for more information about this work:
|
paul@27 | 200 |
|
paul@27 | 201 | http://moinmo.in/ScriptMarket/moinsetup
|
paul@27 | 202 |
|
paul@27 | 203 | The author can be contacted at the following e-mail address:
|
paul@27 | 204 |
|
paul@27 | 205 | paul@boddie.org.uk
|
paul@27 | 206 |
|
paul@27 | 207 | Copyright and licence information can be found in the docs directory - see
|
paul@29 | 208 | docs/COPYING.txt and docs/gpl-3.0.txt for more information.
|
paul@27 | 209 |
|
paul@27 | 210 | Dependencies
|
paul@27 | 211 | ------------
|
paul@27 | 212 |
|
paul@27 | 213 | moinsetup has the following basic dependencies:
|
paul@27 | 214 |
|
paul@27 | 215 | Packages Release Information
|
paul@27 | 216 | -------- -------------------
|
paul@27 | 217 |
|
paul@27 | 218 | CMDsyntax Tested with 0.91
|
paul@27 | 219 | Source: http://www.boddie.org.uk/david/Projects/Python/CMDSyntax/index.html
|
paul@27 | 220 |
|
paul@40 | 221 | New in moinsetup 0.3 (Changes since moinsetup 0.2)
|
paul@40 | 222 | --------------------------------------------------
|
paul@40 | 223 |
|
paul@43 | 224 | * Changed the command syntax to require -m (or --method=) before method
|
paul@43 | 225 | names; improved the error reporting when settings are missing or
|
paul@43 | 226 | inappropriate.
|
paul@43 | 227 | * Flattened the Wiki instance hierarchy, putting the configuration, data,
|
paul@43 | 228 | underlay and htdocs in the same top-level directory.
|
paul@43 | 229 | * Changed the location of MoinMoin 1.9 resources, installing them in the
|
paul@43 | 230 | prefix hierarchy and copying only static resources into Wiki instances.
|
paul@43 | 231 | * Changed the handling of static resources with MoinMoin 1.9 to serve them
|
paul@43 | 232 | separately just as MoinMoin 1.8 does; this makes performance much better
|
paul@43 | 233 | when CGI is used under Apache.
|
paul@43 | 234 | * Moved the editing of the moin script into the setup method so that no
|
paul@43 | 235 | attempt is made to edit system programs.
|
paul@43 | 236 | * Made moin_distribution optional so that when MoinMoin is installed from a
|
paul@43 | 237 | system package, the non-installation actions can still be performed using
|
paul@43 | 238 | shared data typically found in /usr/share/moin.
|
paul@43 | 239 | * Added support for Wiki farms, separate library/site-packages directories,
|
paul@43 | 240 | and site identifiers (based on site names).
|
paul@43 | 241 | * Improved the MoinMoin version detection.
|
paul@40 | 242 |
|
paul@35 | 243 | New in moinsetup 0.2 (Changes since moinsetup 0.1)
|
paul@35 | 244 | --------------------------------------------------
|
paul@35 | 245 |
|
paul@35 | 246 | * Improved OpenID configuration, supporting MoinMoin 1.9, and added support
|
paul@35 | 247 | for other authentication methods.
|
paul@35 | 248 | * Added support for ACL-capable filesystems when setting Wiki permissions.
|
paul@35 | 249 | It can be more convenient to retain read/write access to the installed
|
paul@35 | 250 | files while also granting the Web server user (who need not be in a common
|
paul@35 | 251 | group) access to read and modify the files.
|
paul@35 | 252 | * Added support for configurations employing a separate static resources
|
paul@35 | 253 | directory (such as a typical "htdocs" directory).
|
paul@35 | 254 | * Added a parser installation action.
|
paul@35 | 255 | * Added support for page attachments in the page-packaging action.
|
paul@35 | 256 |
|
paul@27 | 257 | Release Procedures
|
paul@27 | 258 | ------------------
|
paul@27 | 259 |
|
paul@27 | 260 | Update the moinsetup.py __version__ attribute.
|
paul@27 | 261 | Change the version number and package filename/directory in the documentation.
|
paul@27 | 262 | Update the release notes (see above).
|
paul@27 | 263 | Tag, export.
|
paul@27 | 264 | Archive, upload.
|
paul@27 | 265 | Update the ScriptMarket (see above for the URL).
|