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@63 | 120 | The following Web server settings are optional, but they should probably be
|
paul@63 | 121 | investigated and specified:
|
paul@63 | 122 |
|
paul@63 | 123 | web_user The user operating the Web server, typically www-user or
|
paul@63 | 124 | apache. This setting is typically used where the
|
paul@63 | 125 | filesystem supports ACLs and the setfacl program can be
|
paul@63 | 126 | run.
|
paul@63 | 127 |
|
paul@63 | 128 | web_group The group of the user operating the Web server, typically
|
paul@63 | 129 | the same as the user. This setting is typically used where
|
paul@63 | 130 | the ownership of files has to be modified in order to
|
paul@63 | 131 | allow the Web server to access the Wiki programs and
|
paul@63 | 132 | files, thus preserving the original ownership of the
|
paul@63 | 133 | installed files.
|
paul@63 | 134 |
|
paul@36 | 135 | Except for the common_dir setting, site settings are generally only relevant
|
paul@36 | 136 | when configuring and installing a Wiki:
|
paul@27 | 137 |
|
paul@27 | 138 | common_dir The directory in which the Wiki instance being configured
|
paul@27 | 139 | or managed resides (or will reside).
|
paul@27 | 140 |
|
paul@43 | 141 | farm_config A specific Wiki farm configuration file for multiple Wiki
|
paul@43 | 142 | deployments. This overrides the 'common_dir' setting if
|
paul@43 | 143 | used, indicating that a Wiki farm configuration must be
|
paul@62 | 144 | edited when configuring a Wiki, and must refer to an
|
paul@62 | 145 | actual file, not merely a directory.
|
paul@43 | 146 |
|
paul@43 | 147 | site_config A specific configuration file location for a Wiki deployed
|
paul@43 | 148 | within a Wiki farm. This overrides the 'common_dir' setting
|
paul@62 | 149 | if used, and must refer to an actual file, not merely a
|
paul@62 | 150 | directory.
|
paul@43 | 151 |
|
paul@27 | 152 | url_path The URL path (after the host details) of the Wiki.
|
paul@43 | 153 |
|
paul@58 | 154 | static_url_path The URL path (after the host details) of the Wiki's static
|
paul@58 | 155 | resources. This is only required if a limited hosting
|
paul@58 | 156 | environment enforces separate "htdocs" and "cgi-bin"
|
paul@58 | 157 | directories, and the static resources must be placed in
|
paul@58 | 158 | the "htdocs" directory.
|
paul@58 | 159 |
|
paul@27 | 160 | superuser The superuser of the Wiki.
|
paul@43 | 161 |
|
paul@27 | 162 | site_name The name of the Wiki.
|
paul@43 | 163 |
|
paul@43 | 164 | site_identifier An identifier used to refer to the site, typically derived
|
paul@43 | 165 | from 'site_name' if left unspecified, and only really of use
|
paul@43 | 166 | when an Apache site file needs to be written. In limited
|
paul@43 | 167 | hosting environments, this setting has no effect.
|
paul@43 | 168 |
|
paul@27 | 169 | front_page_name The name of the Wiki's front page.
|
paul@43 | 170 |
|
paul@27 | 171 | theme_default The default theme of the Wiki.
|
paul@27 | 172 |
|
paul@43 | 173 | Working with MoinMoin System Installations
|
paul@43 | 174 | ------------------------------------------
|
paul@43 | 175 |
|
paul@43 | 176 | Where MoinMoin has already been installed using a package supplied by an
|
paul@43 | 177 | operating system distribution (such as Debian, Red Hat, Ubuntu), there is no
|
paul@43 | 178 | need to install the software itself. However, it is still necessary to set up
|
paul@51 | 179 | Wiki instances. The moinsetup.cfg.debian file in the examples directory could
|
paul@51 | 180 | be used as a starting point for configuring Wiki instances on Debian systems.
|
paul@43 | 181 |
|
paul@36 | 182 | Limited Hosting Environments
|
paul@36 | 183 | ----------------------------
|
paul@36 | 184 |
|
paul@36 | 185 | Sometimes, the hosting environment in which MoinMoin is to be deployed will be
|
paul@36 | 186 | restrictive or "limited", meaning that substantial configuration of the Web
|
paul@36 | 187 | server will not be possible for the user installing and configuring MoinMoin.
|
paul@36 | 188 | In such environments, users will typically be allowed to install content in
|
paul@36 | 189 | preconfigured directories for static and dynamic content. For example:
|
paul@36 | 190 |
|
paul@36 | 191 | /path/to/www/cgi-bin a dynamic content directory, providing CGI scripts
|
paul@36 | 192 | /path/to/www/htdocs a static content directory, providing Web pages
|
paul@36 | 193 |
|
paul@36 | 194 | To work in such environments, specify the configuration settings in
|
paul@36 | 195 | moinsetup.cfg as follows:
|
paul@36 | 196 |
|
paul@36 | 197 | web_app_dir = /path/to/www/cgi-bin
|
paul@36 | 198 | web_static_dir = /path/to/www/htdocs
|
paul@36 | 199 | web_site_dir =
|
paul@36 | 200 |
|
paul@58 | 201 | url_path = /mysite/cgi-bin
|
paul@58 | 202 | static_url_path = /mysite
|
paul@58 | 203 |
|
paul@43 | 204 | If the web_static_dir setting is left blank, the static resources will be
|
paul@43 | 205 | placed alongside the CGI script. Some environments have .cgi files served as
|
paul@58 | 206 | CGI scripts and other files served statically; in such cases, static_url_path
|
paul@58 | 207 | can also be left blank.
|
paul@43 | 208 |
|
paul@43 | 209 | Inside the directory used to hold static resources, a subdirectory will be
|
paul@43 | 210 | created to hold the static content used by MoinMoin.
|
paul@43 | 211 |
|
paul@60 | 212 | See the moinsetup.cfg.sourceforge file in the examples directory for an
|
paul@60 | 213 | illustration of how Wiki instances can be configured in a restrictive hosting
|
paul@60 | 214 | environment.
|
paul@60 | 215 |
|
paul@43 | 216 | Wiki Farm Environments
|
paul@43 | 217 | ----------------------
|
paul@43 | 218 |
|
paul@43 | 219 | MoinMoin supports the notion of a Wiki farm where a single common configuration
|
paul@43 | 220 | is overridden by configurations for individual Wiki instances. To work in such
|
paul@43 | 221 | environments, specify the configuration settings in moinsetup.cfg as follows:
|
paul@43 | 222 |
|
paul@43 | 223 | farm_config = /path/to/farmconfig.py
|
paul@43 | 224 | site_config = /path/to/wikiname.py
|
paul@36 | 225 |
|
paul@27 | 226 | Examples
|
paul@27 | 227 | --------
|
paul@27 | 228 |
|
paul@27 | 229 | Some of the more useful invocation methods are described below using examples.
|
paul@27 | 230 |
|
paul@43 | 231 | To set up MoinMoin and a Wiki instance (useful when installing MoinMoin
|
paul@43 | 232 | yourself):
|
paul@27 | 233 |
|
paul@43 | 234 | python moinsetup.py -m setup
|
paul@27 | 235 |
|
paul@43 | 236 | To set up only a Wiki instance (useful on a system with MoinMoin installed):
|
paul@43 | 237 |
|
paul@43 | 238 | python moinsetup.py -m setup_wiki
|
paul@27 | 239 |
|
paul@43 | 240 | To set up only a Wiki instance, but using a different configuration file:
|
paul@43 | 241 |
|
paul@43 | 242 | python moinsetup.py -f mywiki.cfg -m setup_wiki
|
paul@27 | 243 |
|
paul@36 | 244 | To change a Wiki configuration setting (for example, the default theme):
|
paul@27 | 245 |
|
paul@43 | 246 | python moinsetup.py -m reconfigure_moin theme_default mercurialwiki
|
paul@27 | 247 |
|
paul@27 | 248 | To install a theme from a directory containing a theme module, css and img
|
paul@27 | 249 | directories (for example, MercurialWikiTheme):
|
paul@27 | 250 |
|
paul@43 | 251 | python moinsetup.py -m install_theme /path/to/MercurialWikiTheme/themes/mercurialwiki
|
paul@27 | 252 |
|
paul@27 | 253 | To install an extension package from a directory containing a setup.py script
|
paul@27 | 254 | (for example, EventAggregator):
|
paul@27 | 255 |
|
paul@43 | 256 | python moinsetup.py -m install_extension_package /path/to/EventAggregator
|
paul@27 | 257 |
|
paul@27 | 258 | To install actions from a directory containing action modules:
|
paul@27 | 259 |
|
paul@43 | 260 | python moinsetup.py -m install_actions /path/to/EventAggregator/actions
|
paul@27 | 261 |
|
paul@27 | 262 | To install macros from a directory containing macro modules:
|
paul@27 | 263 |
|
paul@43 | 264 | python moinsetup.py -m install_macros /path/to/EventAggregator/macros
|
paul@27 | 265 |
|
paul@27 | 266 | To install theme-related resources for an extension from a directory
|
paul@27 | 267 | containing css and img directories:
|
paul@27 | 268 |
|
paul@43 | 269 | python moinsetup.py -m install_theme_resources /path/to/EventAggregator
|
paul@27 | 270 |
|
paul@27 | 271 | To add theme-related resources to existing stylesheets (for example, adding
|
paul@27 | 272 | the event-aggregator.css resource to the screen.css stylesheet for all
|
paul@27 | 273 | installed themes):
|
paul@27 | 274 |
|
paul@43 | 275 | python moinsetup.py -m edit_theme_stylesheet screen.css event-aggregator.css
|
paul@27 | 276 |
|
paul@27 | 277 | To make a page package containing pages to be added to a Wiki:
|
paul@27 | 278 |
|
paul@43 | 279 | python moinsetup.py -m make_page_package pages_dir pages.zip
|
paul@27 | 280 |
|
paul@27 | 281 | To install a page package in a Wiki:
|
paul@27 | 282 |
|
paul@43 | 283 | python moinsetup.py -m install_page_package pages.zip
|
paul@27 | 284 |
|
paul@27 | 285 | Contact, Copyright and Licence Information
|
paul@27 | 286 | ------------------------------------------
|
paul@27 | 287 |
|
paul@27 | 288 | See the following Web page for more information about this work:
|
paul@27 | 289 |
|
paul@27 | 290 | http://moinmo.in/ScriptMarket/moinsetup
|
paul@27 | 291 |
|
paul@27 | 292 | The author can be contacted at the following e-mail address:
|
paul@27 | 293 |
|
paul@27 | 294 | paul@boddie.org.uk
|
paul@27 | 295 |
|
paul@27 | 296 | Copyright and licence information can be found in the docs directory - see
|
paul@29 | 297 | docs/COPYING.txt and docs/gpl-3.0.txt for more information.
|
paul@27 | 298 |
|
paul@27 | 299 | Dependencies
|
paul@27 | 300 | ------------
|
paul@27 | 301 |
|
paul@27 | 302 | moinsetup has the following basic dependencies:
|
paul@27 | 303 |
|
paul@27 | 304 | Packages Release Information
|
paul@27 | 305 | -------- -------------------
|
paul@27 | 306 |
|
paul@27 | 307 | CMDsyntax Tested with 0.91
|
paul@27 | 308 | Source: http://www.boddie.org.uk/david/Projects/Python/CMDSyntax/index.html
|
paul@27 | 309 |
|
paul@58 | 310 | New in moinsetup 0.4 (Changes since moinsetup 0.3)
|
paul@58 | 311 | --------------------------------------------------
|
paul@58 | 312 |
|
paul@63 | 313 | * Added wikiconfig.py, edit-log and event-log permissions/ownership commands
|
paul@63 | 314 | to the postinstall scripts.
|
paul@58 | 315 | * Fixed the .htaccess file location for limited hosting environments, using
|
paul@58 | 316 | the static resources directory in preference to the application directory.
|
paul@58 | 317 | * Added support for separate static URL paths enforced by limited hosting
|
paul@58 | 318 | environments.
|
paul@63 | 319 | * Added web_user and web_group settings.
|
paul@65 | 320 | * Added support for making hierarchical page packages.
|
paul@65 | 321 | * Introduced detection of setup.py files when installing plugins.
|
paul@70 | 322 | * Introduced compilation of plugins upon deployment and more restrictive
|
paul@70 | 323 | permissions on files in the plugins directory.
|
paul@58 | 324 |
|
paul@40 | 325 | New in moinsetup 0.3 (Changes since moinsetup 0.2)
|
paul@40 | 326 | --------------------------------------------------
|
paul@40 | 327 |
|
paul@43 | 328 | * Changed the command syntax to require -m (or --method=) before method
|
paul@43 | 329 | names; improved the error reporting when settings are missing or
|
paul@43 | 330 | inappropriate.
|
paul@43 | 331 | * Flattened the Wiki instance hierarchy, putting the configuration, data,
|
paul@47 | 332 | underlay and htdocs in the same top-level directory. (See the migration
|
paul@47 | 333 | section in the documentation for information on updating the hierarchy.)
|
paul@43 | 334 | * Changed the location of MoinMoin 1.9 resources, installing them in the
|
paul@43 | 335 | prefix hierarchy and copying only static resources into Wiki instances.
|
paul@43 | 336 | * Changed the handling of static resources with MoinMoin 1.9 to serve them
|
paul@43 | 337 | separately just as MoinMoin 1.8 does; this makes performance much better
|
paul@43 | 338 | when CGI is used under Apache.
|
paul@43 | 339 | * Moved the editing of the moin script into the setup method so that no
|
paul@43 | 340 | attempt is made to edit system programs.
|
paul@43 | 341 | * Made moin_distribution optional so that when MoinMoin is installed from a
|
paul@43 | 342 | system package, the non-installation actions can still be performed using
|
paul@43 | 343 | shared data typically found in /usr/share/moin.
|
paul@43 | 344 | * Added support for Wiki farms, separate library/site-packages directories,
|
paul@43 | 345 | and site identifiers (based on site names).
|
paul@43 | 346 | * Improved the MoinMoin version detection.
|
paul@52 | 347 | * Added an event handler installation action.
|
paul@40 | 348 |
|
paul@35 | 349 | New in moinsetup 0.2 (Changes since moinsetup 0.1)
|
paul@35 | 350 | --------------------------------------------------
|
paul@35 | 351 |
|
paul@35 | 352 | * Improved OpenID configuration, supporting MoinMoin 1.9, and added support
|
paul@35 | 353 | for other authentication methods.
|
paul@35 | 354 | * Added support for ACL-capable filesystems when setting Wiki permissions.
|
paul@35 | 355 | It can be more convenient to retain read/write access to the installed
|
paul@35 | 356 | files while also granting the Web server user (who need not be in a common
|
paul@35 | 357 | group) access to read and modify the files.
|
paul@35 | 358 | * Added support for configurations employing a separate static resources
|
paul@35 | 359 | directory (such as a typical "htdocs" directory).
|
paul@35 | 360 | * Added a parser installation action.
|
paul@35 | 361 | * Added support for page attachments in the page-packaging action.
|
paul@35 | 362 |
|
paul@27 | 363 | Release Procedures
|
paul@27 | 364 | ------------------
|
paul@27 | 365 |
|
paul@27 | 366 | Update the moinsetup.py __version__ attribute.
|
paul@27 | 367 | Change the version number and package filename/directory in the documentation.
|
paul@27 | 368 | Update the release notes (see above).
|
paul@27 | 369 | Tag, export.
|
paul@27 | 370 | Archive, upload.
|
paul@27 | 371 | Update the ScriptMarket (see above for the URL).
|