| Index: trunk/phase3/docs/distributors.txt |
| — | — | @@ -0,0 +1,192 @@ |
| | 2 | +This document is intended to provide useful advice for parties seeking to |
| | 3 | +redistribute MediaWiki to end users. It's targeted particularly at maintainers |
| | 4 | +for Linux distributions, since it's been observed that distribution packages of |
| | 5 | +MediaWiki often break. We've consistently had to recommend that users seeking |
| | 6 | +support use official tarballs instead of their distribution's packages, and |
| | 7 | +this often solves whatever problem the user is having. It would be nice if |
| | 8 | +this could change. |
| | 9 | + |
| | 10 | +== Background: why web applications are different == |
| | 11 | + |
| | 12 | +MediaWiki is intended to be usable on any web host that provides support for |
| | 13 | +PHP and a database. Many users of low-end shared hosting have very limited |
| | 14 | +access to their machine: often only FTP access to some subdirectory of the web |
| | 15 | +root. Support for these users entails several restrictions, such as: |
| | 16 | + |
| | 17 | + 1) We cannot require installation of any files outside the web root. Few of |
| | 18 | + our users have access to directories like /usr or /etc. |
| | 19 | + 2) We cannot require the ability to run any utility on the command line. |
| | 20 | + Many shared hosts have exec() and similar PHP functions disabled. |
| | 21 | + 3) We cannot assume that the software has write access anywhere useful. The |
| | 22 | + user account that MediaWiki (including its installer) runs under is often |
| | 23 | + different from the account the user used to upload the files, and we might be |
| | 24 | + restricted by PHP settings such as safe mode or open_basedir. |
| | 25 | + 4) We cannot assume that the software even has read access anywhere useful. |
| | 26 | + Many shared hosts run all users' web applications under the same user, so |
| | 27 | + they can't rely on Unix permissions, and must forbid reads to even standard |
| | 28 | + directories like /tmp lest users read each others' files. |
| | 29 | + 5) We cannot assume that the user has the ability to install or run any |
| | 30 | + programs not written as web-accessible PHP scripts. |
| | 31 | + |
| | 32 | +Since anything that works on cheap shared hosting will work if you have shell |
| | 33 | +or root access too, MediaWiki's design is based around catering to the lowest |
| | 34 | +common denominator. Although we support higher-end setups as well (like |
| | 35 | +Wikipedia!), the way many things work by default is tailored toward shared |
| | 36 | +hosting. These defaults are unconventional from the point of view of normal |
| | 37 | +(non-web) applications -- they might conflict with distributors' policies, and |
| | 38 | +they certainly aren't ideal for someone who's installing MediaWiki as root. |
| | 39 | + |
| | 40 | +== Directory structure == |
| | 41 | + |
| | 42 | +Because of constraint (1) above, MediaWiki does not conform to normal |
| | 43 | +Unix filesystem layout. Hopefully we'll offer direct support for standard |
| | 44 | +layouts in the future, but for now *any change to the location of files is |
| | 45 | +unsupported*. Moving things and leaving symlinks will *probably* not break |
| | 46 | +anything, but it is *strongly* advised not to try any more intrusive changes to |
| | 47 | +get MediaWiki to conform more closely to your filesystem hierarchy. Any such |
| | 48 | +attempt will almost certainly result in unnecessary bugs. |
| | 49 | + |
| | 50 | +The standard recommended location to install MediaWiki, relative to the web |
| | 51 | +root, is /w (so, e.g., /var/www/w). Rewrite rules can then be used to enable |
| | 52 | +"pretty URLs" like /wiki/Article instead of /w/index.php?title=Article. (This |
| | 53 | +is the convention Wikipedia uses.) In theory, it should be possible to enable |
| | 54 | +the appropriate rewrite rules by default, if you can reconfigure the web |
| | 55 | +server, but you'd need to alter LocalSettings.php too. See |
| | 56 | +<http://www.mediawiki.org/wiki/Manual:Short_URL> for details on short URLs. |
| | 57 | + |
| | 58 | +If you really must mess around with the directory structure, note that the |
| | 59 | +following files *must* all be web-accessible for MediaWiki to function |
| | 60 | +correctly: |
| | 61 | + |
| | 62 | + * api.php, img_auth.php, index.php, mwScriptLoader.php, opensearch_desc.php, |
| | 63 | + profileinfo.php, redirect.php, thumb.php, trackback.php. These are the entry |
| | 64 | + points for normal usage. This list may be incomplete and is subject to |
| | 65 | + change. |
| | 66 | + * config/index.php: Used for web-based installation (sets up the database, |
| | 67 | + prompts for the name of the wiki, etc.). No command-line installation is |
| | 68 | + currently available. |
| | 69 | + * images/: Used for uploaded files. This could be somewhere else if |
| | 70 | + $wgUploadDirectory and $wgUploadPath are changed appropriately. |
| | 71 | + * skins/*/: Subdirectories of skins/ contain CSS and JavaScript files that |
| | 72 | + must be accessible to web browsers. The PHP files and Skin.sample in skins/ |
| | 73 | + don't need to be accessible. This could be somewhere else if |
| | 74 | + $wgStyleDirectory and $wgStylePath are changed appropriately. |
| | 75 | + * extensions/: Many extensions include CSS and JavaScript files in their |
| | 76 | + extensions directory, and will break if they aren't web-accessible. Some |
| | 77 | + extensions might theoretically provide additional entry points as well, at |
| | 78 | + least in principle. |
| | 79 | + |
| | 80 | +But all files should keep their position relative to the web-visible |
| | 81 | +installation directory no matter what. If you must move includes/ somewhere in |
| | 82 | +/usr/share, provide a symlink from /var/www/w. If you don't, you *will* break |
| | 83 | +something. You have been warned. |
| | 84 | + |
| | 85 | +== Configuration == |
| | 86 | + |
| | 87 | +MediaWiki is configured using LocalSettings.php. This is a PHP file that's |
| | 88 | +generated when the user visits config/index.php to install the software, and |
| | 89 | +which the user can edit by hand thereafter. It's just a plain old PHP file, |
| | 90 | +and can contain any PHP statements. It usually sets global variables that are |
| | 91 | +used for configuration, and includes files used by any extensions. |
| | 92 | + |
| | 93 | +Distributors cannot easily add extra statements to the autogenerated |
| | 94 | +LocalSettings.php at the present time -- although hacking config/index.php |
| | 95 | +would work. It would be nice if this situation could be improved. |
| | 96 | + |
| | 97 | +Some configuration options that distributors might be in a position to set |
| | 98 | +intelligently: |
| | 99 | + |
| | 100 | + * $wgEmergencyContact: An e-mail address that can be used to contact the wiki |
| | 101 | + administrator. By default, "wikiadmin@$wgServerName". |
| | 102 | + * $wgPasswordSender: The e-mail address to use when sending password e-mails. |
| | 103 | + By default, "MediaWiki Mail <apache@$wgServerName>". |
| | 104 | + * $wgSMTP: Can be configured to use SMTP for mail sending instead of PHP |
| | 105 | + mail(). |
| | 106 | + |
| | 107 | +== Documentation == |
| | 108 | + |
| | 109 | +MediaWiki's official documentation is split between two places: the source |
| | 110 | +code, and <http://www.mediawiki.org/>. The source code documentation is written |
| | 111 | +exclusively by developers, and so is likely to be reliable (at worst, |
| | 112 | +outdated). However, it can be pretty sparse. mediawiki.org documentation is |
| | 113 | +often much more thorough, but it's maintained by a wiki that's open to |
| | 114 | +anonymous edits, so its quality is sometimes sketchy -- don't assume that |
| | 115 | +anything there is officially endorsed! |
| | 116 | + |
| | 117 | +== Upstream == |
| | 118 | + |
| | 119 | +MediaWiki is a project hosted and led by the Wikimedia Foundation, the |
| | 120 | +not-for-profit charity that operates Wikipedia. Wikimedia employs the lead |
| | 121 | +developer and several other paid developers, but commit access is given out |
| | 122 | +liberally and there are multiple very active volunteer developers as well. A |
| | 123 | +list of developers can be found at <http://www.mediawiki.org/wiki/Developers>. |
| | 124 | + |
| | 125 | +MediaWiki's bug tracker is at <https://bugzilla.wikimedia.org>. However, most |
| | 126 | +developers follow the bug tracker little or not at all. The best place to |
| | 127 | +post if you want to get developers' attention is the wikitech-l mailing list |
| | 128 | +<https://lists.wikimedia.org/mailman/listinfo/wikitech-l>. Posts to wikitech-l |
| | 129 | +will inevitably be read by multiple experienced MediaWiki developers. There's |
| | 130 | +also an active IRC chat at <irc://irc.freenode.net/mediawiki>, where there are |
| | 131 | +usually several developers at reasonably busy times of day. |
| | 132 | + |
| | 133 | +Unfortunately, we don't have a very good system for patch review. Patches |
| | 134 | +should be submitted on Bugzilla (as unified diffs produced with "svn diff" |
| | 135 | +against the latest trunk revision), but many patches languish without review |
| | 136 | +until they bitrot into uselessness. You might want to get a developer to |
| | 137 | +commit to reviewing your patch before you put too much effort into it. |
| | 138 | +Reasonably straightforward patches shouldn't be too hard to get accepted if |
| | 139 | +there's an interested developer, however -- posting to Bugzilla and then |
| | 140 | +dropping a note on wikitech-l if nobody responds is a good tactic. |
| | 141 | + |
| | 142 | +All redistributors of MediaWiki should be subscribed to mediawiki-announce |
| | 143 | +<https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce>. It's |
| | 144 | +extremely low-traffic, with an average of less than one post per month. All |
| | 145 | +new releases are announced here, including critical security updates. |
| | 146 | + |
| | 147 | +== Useful software to install == |
| | 148 | + |
| | 149 | +There are several other pieces of software that MediaWiki can make good use of. |
| | 150 | +Distributors might choose to install these automatically with MediaWiki and |
| | 151 | +perhaps configure it to use them (see Configuration section of this document): |
| | 152 | + |
| | 153 | + * APC (Alternative PHP Cache), XCache, or similar: Will greatly speed up the |
| | 154 | + execution of MediaWiki, and all other PHP applications, at some cost in |
| | 155 | + memory usage. Will be used automatically for the most part. |
| | 156 | + * clamav: Can be used for virus scanning of uploaded files. Enable with |
| | 157 | + "$wgAntivirus = 'clamav';". |
| | 158 | + * DjVuLibre: Allows processing of DjVu files. To enable this, set |
| | 159 | + "$wgDjvuDump = 'djvudump'; $wgDjvuRenderer = 'ddjvu'; $wgDjvuTxt = 'djvutxt';". |
| | 160 | + * HTML Tidy: Fixes errors in HTML at runtime. Can be enabled with "$wgUseTidy |
| | 161 | + = true;". |
| | 162 | + * ImageMagick: For resizing images. "$wgUseImageMagick = true;" will enable |
| | 163 | + it. PHP's GD can also be used, but ImageMagick is preferable. |
| | 164 | + * Squid: Can provide a drastic speedup and a major cut in resource |
| | 165 | + consumption, but enabling it may interfere with other applications. It might |
| | 166 | + be suitable for a separate mediawiki-squid package. For setup details, see: |
| | 167 | + <http://www.mediawiki.org/wiki/Manual:Squid_caching> |
| | 168 | + * rsvg or other SVG rasterizer: ImageMagick can be used for SVG support, but |
| | 169 | + is not ideal. Wikipedia (as of the time of this writing) uses rsvg. To |
| | 170 | + enable, set "$wgSVGConverter = 'rsvg';" (or other as appropriate). |
| | 171 | + * texvc: Included with MediaWiki. Instructions for compiling and |
| | 172 | + installing it are in the math/ directory. |
| | 173 | + |
| | 174 | +MediaWiki uses some standard GNU utilities as well, such as diff and diff3. If |
| | 175 | +these are present in /usr/bin or some other reasonable location, they will be |
| | 176 | +used automatically. |
| | 177 | + |
| | 178 | +MediaWiki also has a "job queue" that handles background processing. Because |
| | 179 | +shared hosts often don't provide access to cron, the job queue is run on every |
| | 180 | +page view by default. This means the background tasks aren't really done in |
| | 181 | +the background. Busy wikis can set $wgJobRunRate to 0 and run |
| | 182 | +maintenance/runJobs.php periodically out of cron. Distributors probably |
| | 183 | +shouldn't set this up as a default, however, since the extra cron job is |
| | 184 | +unnecessary overhead for a little-used wiki. |
| | 185 | + |
| | 186 | +== Web server configuration == |
| | 187 | + |
| | 188 | +MediaWiki includes several .htaccess files to restrict access to some |
| | 189 | +directories. If the web server is not configured to support these files, and |
| | 190 | +the relevant directories haven't been moved someplace inaccessible anyway (e.g. |
| | 191 | +symlinked in /usr/share with the web server configured to not follow symlinks), |
| | 192 | +then it might be useful to deny web access to those directories in the web |
| | 193 | +server's configuration. |
| Property changes on: trunk/phase3/docs/distributors.txt |
| ___________________________________________________________________ |
| Name: svn:eol-style |
| 1 | 194 | + native |