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