View source for Mediawiki notes

{{old}}
{{notes}}

Mediawiki is the software used in wikipedia, and in many others, including this wiki. 


=Setting up mediawiki=

Roughly:

* Install database
* Set up apache
* Unpack the mediawiki archive
* Configure
* Configure some more


==Installing MySQL==
There is postgres support now, and while I personally consider that a more mature database engine, I'm not sure how mature mediawiki's interface to it is.

There's probably a package manager installation you can use to install mysql, though there's always some configuration involved. There are plenty of FAQs out there.


==Setting up apache==
Nothing special. In my case, I run various hosts on the same server, so I set these things in vhosts. For example: the entire entry for this wiki used to be:
 <VirtualHost 145.99.239.174>
   ServerName helpful.knobs-dials.com
   DocumentRoot /var/www/helpful
   ServerAdmin  me@example.com
   <Directory  /var/www/helpful>
      Options            None
      AllowOverride      None
      Order allow,deny
      Allow from All
   </Directory>
 </VirtualHost>

When edited to your wishes, make apache reload its configuration. In my case:
 /etc/init.d/apache2 reload

==Unpacking the archive==
You wouldn't be here if your distro had mediawiki in a package, right?

Go to the apache directory you want the wiki in, <tt>/var/www/helpful</tt> in the above case. 

Then unpack with something like:
<code lang="bash">
tar xf mediawiki-1.3.5.tgz 
</code>

You will probably have to change ownership on the files to be safe, usually something like the following will do:
<code lang="bash">
chown apache:apache /var/www/helpful -R      # ...or whatever the applicable user is called on your system
</code>

==Configuration: Wiki and database setup==


You should '''temporarily''' chmod a+w the config directory:
<code lang="bash">
chmod a+w config/
</code>
...so that the config script you're about to run can create a new configuration file.


When you surf to the URL you just installed on, it will tell you the wiki is not configured, and prompt you to do so. <!--(technically anyone could do so, and you could configure apache to shield this from others, but chances are no one knows about this just-configured site so it's rarely worth the effort)-->

As to the database part: 
* it's easiest if you have the mysql administrative login, as this will enable the setup script to create a unique database for the wiki. 
* If not, you or the sysadmin should (create a database and) give you a login for a specific database
** If the sysadmin only gives one database to each of its users, e.g. in some shared hosting, you can shove it in that alongside your other tables. You probably want to use mediawiki's option to prefix the tables, to make it a little more obvious what's what, and avoid name collisions.


After you submit this config page and everything goes well, it will tell you that <tt>LocalSettings.php</tt> currently in the <tt>config/</tt> subdirectory needs to be moved to the main directory. 

At this point your wiki should be functional.


To be safe, you should <tt>chmod go-w LocalSettings.php</tt>, otherwise people may be, in theory, be able to edit the settings file.

==Some minor setup trouble==
==="The upload directory (public) is not writable by the webserver."===

Mean the <tt>images/</tt> directory isn't writeable by the webserver.
{{comment|(I'm not sure what 'public' refers to. There is no directory with that name in mediawiki tree)}}

Often you can chown/chgrp to change ownership (if needed), 
and a {{inlinecode|chmod -R g+w images}} if you changed the ''group'' to the webserver group.

===Mediawiki and PHP safe mode===

<!--
It seems the central wiki features will work in safe mode. 
Don't expect all extensions to work in safe mode.
-->


====imagemagick or not; ''"Error Creating Thumbnail: Unable to run external programs in Safe Mode"''====

Assuming that you can't avoid safe mode (e.g. shared hosting with paranoid tendencies), then you'll probably want to change <tt>LocalSettings.php</tt> to set:
 $wgUseImageMagick = false;

This means it'll use PHP's image functions instead of external calls to imagemagick, which means fewer file formats are supported (but if PNG, GIF and JPG covers all your use  then that's no problem).

See also http://www.mediawiki.org/wiki/Manual:$wgUseImageMagick

<!--
(note that in general, the safe mode warning can also come from PHP installations that don't use safe mode but still disable specific functions)
-->

===diffs; ''File(/usr/bin/diff3) is not within the allowed path(s)''===

Unsure; there may not be a way around this one.{{verify}}


<!--
==Speeding up mediawiki==

A very basic mediawiki installation can be a bit sluggish, although if it's noticeable then your hosting may be part of the problem.

There are various types of caches that can speed up page views,
some of which makes mediawiki just cache reusable data (some of which avoids database accesses),
some of which speed up PHP.

In general, caching can be in a DB table, in Turck MMCache, or memcached - see http://www.mediawiki.org/wiki/Manual:$wgParserCacheType
If DB latency is part of your sluggishness, then storing in the DB probably won't help much, and may even be worse.

Use of memcached also lets you distribute the load of generation of cached data.

To separate multiple wikis using one cache, see http://www.mediawiki.org/wiki/Manual:$wgRenderHashAppend

Many of these options won't be available on shared hosting, though.

See http://www.mediawiki.org/wiki/Manual:Cache



'''Caching rendered pages''' - on many wikis, most views will be regular page vies by people not logged in, so caching that version once produced into HTML is an easy improvement.
It can be simplest to use an external cache in front of the web servers, particularly if you run multiple web servers for the wiki (or just in general). 

If that's not an option (e.g. shared hosting),
you can try to see how much doing this on the filesystem will help.
Caveats: 
* doesn't play nice with some dynamic content, changes in extensions, and such.
* only applies regular views, only to users not logged in, and under a few more conditions.

See http://www.mediawiki.org/wiki/Manual:File_cache



'''Parser cache''' - part of mediawiki that produces a page under a given set of settings. 
For exactly matching requests, and in particular longer pages, caching may help generation time.

See http://www.mediawiki.org/wiki/Manual:$wgEnableParserCache



'''Object Cache''' - a PHP thing that mostly avoids re-parsing the PHP every request.
Mediawiki should work fine with APC, Turck MMCache, and earlier versions of eAccelerator{{verify}}. 

There are a few limitations - shared hosting rarely allows it, 
it seems APC doesn't like threaded MPMs (it didn't at one point - it's possible that has been fixed),
and past versions of these things have been known to be buggy.
-->

=Updating mediawiki=

Mediawiki have a good resource: http://www.mediawiki.org/wiki/Manual:Upgrading


Summary:
* You should back up the documentroot and the database it uses. I've done a handful of updates and never had it mess things up, but having a ''lot'' of data tied in some undefined half-updated state won't be fun.

* If you have a vanilla install, and the only thing that is specific to your site is your LocalSettings.php, upgrading is very simple. If you have further customisation (extensions, altered style) then you'll need to do a little more work copying and/or updating them.

* '''Most of the work''': you can copy the newer version's directory structure over the older {{comment|(overwrites many things, but not LocalSettings.php or uploaded files)}}, run its <tt>maintenance/update.php</tt> from the shell to update the database, wait for it to finish, and be done.
** <tt>update.php</tt> can update from fairly old versions. If you have something extremely old you may have to do it in multiple steps{{verify}}, but typically you don't.

* Database-wise: Depending on how you set up the database user's permissions, you may need to temporarily grant a little more while upgrading. For example, updating probably needs to CREATE things, which you may have restricted.

* On a live site you may want to temporarily put up a maintenance message. {{comment|(Consider [[Apache_config_and_.htaccess_-_security#Downtime_notice_trick|this trick]])}}

* You typically want to check that things still work. Most things are tested if you browse around a few pages, edit one (perhaps preferably one that then uses an extension), upload a file.


<!--
=Transplanting mediawiki=

* Move the database contents
** you may need to give it a different name

* Move the files
** Will include all plugins (though you may want to look at underlying)
** Tweak the settings for the database config


-->

=Spam protection=
If your wiki is public, shows up in search engines, and is editable by everyone, it'll eventually get spammed.


===Content===

There are various solutions, and which is handiest depends on how you use the wiki (and on the other spam protection you use).

You can disable anonymous edits and force people to register, log in, but that will probably scare potential editors away, which really isn't the point.


Spam filters are probably nicer. Some options:

* a CAPTCHA, often using [http://www.mediawiki.org/wiki/Extension:ConfirmEdit ConfirmEdit], or [http://www.mediawiki.org/wiki/Extension:ReCAPTCHA reCAPTCHA].
** note most CAPTCHAs have been broken to some degree
** can be made to trigger only under specific conditions, e.g. 
*** to never bug admin edits
*** never bother logged-in users - which on lower-use wikis can combine well with account creation moderation (see below)
*** only trigger when new external (http) links are added
*** and more


* block specific text patterns completely
** consider hosts/domains commonly linked to, common medicine names, etc. There's [http://www.mediawiki.org/wiki/Manual:%24wgSpamRegex $wgSpamRegex] exists in the mediawiki core. 
** But you ''do'' need to know [[regular expressions]]
** and it's time-consuming to be thorough with while not overly restrictive 
** ...you'ld probably want some text patterns to trigger captcha rather than block them


A combination of these and more may be best,
particularly if you want to bother real users as little as possible.
<!--
There is some text that you know you never want, 
there is some text that you probably want to trigger a CAPTCHA
and there are some users you never want to bother.

Once you have that set up, you can keep balancing the manual work for things that slip through and new things that need to be added.


CAPTCHAs are potentially nice because they don't block, and will will bother people only after they submit - at which time they'll probably take the few seconds to submit what they probably took longer to type out. (still annoying. And sort of sneaky in that you don't chase them away with a captcha before starting to type anyway)
-->



===Accounts===

I now see a few new accounts per day.
It seems reCAPTCHA is relatively broken.

On lower-used wikis, you can moderate account creation using the [http://www.mediawiki.org/wiki/Extension:ConfirmAccount ConfirmAccount] extension.

<!--
(You may also be careful with mail settings - there seem to be scripts that generate users just to send mail to the configured address)
-->


===See also (spam)===

For more details and further options, see:
* http://www.mediawiki.org/wiki/Manual:Combating_spam
* http://www.umasswiki.com/wiki/UMassWiki:Blocking_Spam_in_MediaWiki

=Optional=
==TeX formatting==
To get the wiki to use TeX formula formatting, you need you need <tt>ocaml</tt> (a functional language) installed, and then:
* compile the code in <tt>math/</tt>. (run <tt>make</tt>)
* set <tt>$wgUseTeX = true;</tt> in <tt>LocalSettings.php</tt>

The reason for this executable is protecting you from risky TeX. The app parses and filters the Tex. This also means it only allows basic math TeX, not advanced LaTeX commands.


==Aesthetics==
===Changing the picture===
That top left one there - it's handy to tell wikis apart.


In recent versions, you can set $wgLogo to the URL you want.


In older versions, you had to change the stylesheet or the image it pointed to (by default all skins point the same way, so changing the image could be handier).

I personally find it easiest to find the image, copy it out, edit it, and copy the result back in. This way it is the right size and starts off being transparent and save right (it's a PNG with alpha transparency). 

The image's location changed a few times between versions:
* 1.4: <tt>skins/common/images/wiki.png</tt>
* 1.3: <tt>stylesheets/images/wiki.png</tt> 

<!--
stylesheets/monobook/images/wiki.png
-->

===Altering the menu===
Smaller wikis will probably have no use for 'current events' or 'community portal'. How to do this depends on the version.

For 1.5, you should visit the wiki's MediaWiki:Sidebar page. The list presented either is in the reference-to-page-with-url|reference-to-page-with-name form. These references are into the Mediawiki: namepsace, so for the Categories link on the left I added:
 ** categories-url|categories
And made the pages 
* Mediawiki:categories-url with contents: "Special:Categories"
* Mediawiki:categories with contents: "Categories" (it seemed to exist already?)


For this and many similar alterations, see [http://meta.wikimedia.org/wiki/MediaWiki_FAQ The wikiMedia FAQ] and the [http://meta.wikimedia.org/ Mediawiki meta-wiki].


===Hiding that index.php===
This is done with black magic, better known as <tt>mod_rewrite</tt> (see [http://meta.wikimedia.org/wiki/Rewrite_Rules this]), although there are other ways.

=Maintenance=

===Backup===
{{stub}}

Most of the information sits in the database, which means that a database backup will get most content, and you can restore such a backup into the database later.

In the case of mysql, this typically means a [[MySQL_notes#SQL-level_dump_.28mysqldump.29|mysqldump]].
Be careful of character set corruption, though.


There are also a number of things stored on the filesystem, including:
* LocalSettings.php
* extensions (and their settings)
* Uploaded files  (the database will reference them).
* ...more

A more complete backup inclides them too.
The simplest solution is probably to tar the entire thing (the virtualhost's documentroot), though you can probably exclude things like the image cache{{verify}}




===mediawiki and mangled characters===
{{stub}}

After quite a few upgrades I've had mangled characters.

Note that there is a big difference between text being mangled in storage,
and data only being retrieved/presented incorrectly.

For mediawiki it's usually the second, because the frontend is UTF-8 throughout.


When you're upgrading/loading data from a rather old mediawiki version (which ones?{{verify}}) 
or from MySQL versions before 4.1, there are a number of details to know about to do the conversion properly.
See e.g. http://www.mediawiki.org/wiki/Manual:Backing_up_a_wiki



Note that this is about database schema. No data changes when you upgrade. 
Particularly when updating between more recent installations, 
the likely problem is unwanted implicit database translation,
such as having the wrong ''connection'' charset.

This may come down to looking at $wgDBmysql5 in your LocalSettings.php.
Very roughly, if it's true then mediawiki assumes UTF-8 and if it's false it assumes latin1. 
If setting:
<code lang="php">
$wgDBmysql5 = true;  # possibly $wgDBmysql4 = false;, though it's deprecated in recent versions
</code>
...solves your problem, then yay.
If you want to understand the problem, there's more reading to do (I'd appreciate a summary if you do:) ).


<!--
How exactly this is best solved depends a little on how the wiki was created, what you told the config form at the time. The options on recent versions are:
* MySQL 4.1/5.0 binary
** apparently slightly more efficient than the non-binary form, and not limited to the BMP
** can't be viewed directly in things like pma
* MySQL 4.1/5.0 UTF-8
** MySQL won't store all Unicode characters (limited to BMP, so possibly stored as UCS2)
* MySQL 4.0 backwards-compatible UTF-8
** restoring a backup (and moving/upgrading) may be problematic. 
** Don't use this on MySQL versions 4.1 or later.

-->



===Shrinking the database===

See also http://www.mediawiki.org/wiki/Manual:Reduce_size_of_the_database





Over time, most of the size of the database is old revisions, kept as text (uncompressed, for speed reasons).

The largest space user are usually old revisions, so compressing or even deleting them usually shrinks the database a lot.

You can:
* '''compress old revisions'''
** old articles are kept uncompressed by default for speed reasons. compressed revisions are slightly slower to use, but (depending on the amount of old revisions) may save a lot of database storage
** Sometimes causes trouble (at least, I lost some pages in the process) -- so make a backup that is easy to restore. (TODO: Search for reports mentioning "Call to a member function uncompress() on a non-object")
** done by a shell script <!--
(<tt>php maintenance/storage/compressOld.php</tt>)
-->

* '''delete old revisions'''
** you give up any and all ability to look back to and restore from old data (yes, you can save a database backup, but those are not that easy to use)
** You can do this selectively or globally. See [http://www.mediawiki.org/wiki/Manual:FAQ#How_do_I_delete_an_old_version_of_a_page.3F]

* '''delete archived pages''' 
** ...which refers to deleted pages that have history, which are kept around in case you want to undelete them. 
** Usually little space compared to old revisions
** Can be done with ({{inlinecode|TRUNCATE archive;}} to remove the references to archive entries, then a {{inlinecode|php maintenance/purgeOldText.php --purge}} to remove the related text content.

<!--
* delete old image versions (you can do this manually)
-->


<!--
===Images===

You shouldn't touch directories that relate to old revisions and archived things, because the database keeps tracks of those. There's usually something in the interface and/or maintenance scripts instead.

Image-related directories:
* <tt>images/temp</tt> - used by uploads. Usually cleared automatically (there have been a few bugs)
* <tt>images/tmp</tt> - other temporary use (e.g. used in TeX compilation)

* <tt>images/0</tt> .. <tt>images/f</tt> - originals of images in current use
* <tt>images/thumb - various sizes of thumbnails 
** can be manually cleared to regenerate only those you need -- but I've had trouble with this not always happening without some help (so be sure you won't create a bunch of work for yourself)

* <tt>images/archive</tt> - older revisions of images currenty in use. You can choose to delete these if you wish {{comment|(though this only really hides them from direct use; see below)}}

* <tt>images/deleted</tt> - images considered deleted (e.g. including non-current revisions that you deleted), to allow undelete {{comment|(a relatively new feature)}}
** can be purged via maintenance/deleteArchivedFiles.php {{verify}}

* <tt>images/math</tt>
** Used if you use the TeX rendering extension



====Less space====

Images take space because of 
the original file, 
* thumb/ various sizes of thumbnails. May be deleted, will be automatically regenerated when needed
and because of archived images.


Note that no thumbnails are created for small images.

You can delete old file/image versions (via the file's page). 



====See also====
http://www.mediawiki.org/wiki/Manual_talk:Image_Administration



===Shrinking mediawiki's size===
Note that if a large enough wiki, much of the disk use is images.

You could:
* delete skins you don't use (...and none of your users use)
* delete languages you don't use
-->

=Writing template pages=

See also [http://meta.wikimedia.org/wiki/Help:Template]


===Arguments===
====Using their values====
You can use positional and named parameters:
* positional: <tt>&#x7b;&#x7b;&#x7b;1&#x7d;&#x7d;&#x7d;</tt>  (one-based counting)
* named:      <tt>&#x7b;&#x7b;&#x7b;command&#x7d;&#x7d;&#x7d;</tt> 

References to things that are undefined are taken literally, so as a bunch of accoladed characters. 
You usually want a default value, using the form {{inlinecode|<nowiki>&#x7B;&#x7B;&#x7B;1|&#x7D;&#x7D;&#x7D;</nowiki>}}, which in this case means an empty string.


'''Numbered parameters'''

For an example, to link to documentation with a configurable URL and an optional fragment, make the template something like:
 <nowiki>[http://example.com/doc/{{{1}}}.html#{{{2|}}} Documentation for {{{1}}}]</nowiki>
which is then usable like {{inlinecode|<nowiki>&#x7B;&#x7B;docs|progname&#x7D;&#x7D;</nowiki>}}
and like {{inlinecode|<nowiki>&#x7B;&#x7B;docs|fileformats|inputfiles&#x7D;&#x7D;</nowiki>}}. Of course, this does cheat a little with the # without escaping.
You often have to start playing with more advanced logic - which is hard to do without mediawiki extensions for specifically that purpose.


'''Named parameters'''

For example, templates defined like:
 Doc set: &#x7b;&#x7b;&#x7b;1&#x7d;&#x7d;&#x7d;
 Command: &#x7b;&#x7b;&#x7b;command&#x7d;&#x7d;&#x7d;
can be used as:
 &#x7b;&#x7b;docs|basic|command=sleep&#x7d;&#x7d;


Numeric parameters are essentially auto-named:
 &#x7b;&#x7b;docs|1=basic|command=sleep&#x7d;&#x7d;

The difference between 
 &#x7b;&#x7b;test||foo&#x7d;&#x7d;
 &#x7b;&#x7b;test|2=foo&#x7d;&#x7d;
...is that in the former, argument 1 is an empty string, whereas in the second it is undefined.



When passing in a pipe meant to be interpreted only as the results of the template, for example in a table row, use &#x7b;&#x7b;!&#x7d;&#x7d;.

when you want it uninterpreted, it may be simplest to use the HTML entity, &amp;#x7c;.

====Character safety====
When placing strings into URLs, you probably want to know about what media calls [http://www.mediawiki.org/wiki/Help:Magic_words magic word], specifically the <tt>urlencode:</tt> one, so that certain characters will not mess things up for, in this case, URL values.


For example, The [[Template:Imagesearch|&#x7b;&#x7b;imagesearch&#x7d;&#x7d;]] template on this wiki contains:
 <nowiki>[http://www.google.com/images?q=({{urlencode:{{{1|test}}}}}) {{{2|{{{1|image search}}}}}}]</nowiki>

The search term falls back to test (because example), the link text is the second argument if you have one, the query string if you did not<!--, so e.g. 
* {{imagesearch|sugar}} <nowiki>{{imagesearch|sugar}}</nowiki>: 
* {{imagesearch|sucrose OR fructose OR glucose|sugar molecules}}: <nowiki>{{imagesearch|sucrose OR fructose OR glucose|sugar molecules}}</nowiki>-->


Actually, there are three urlencode variants: QUERY (the default), WIKI, and PATH. See
http://www.mediawiki.org/wiki/Help:Magic_words#URL_data for details

===Including help on template pages===
On Template: pages, you can use &lt;noinclude&gt; (or &lt;includeonly&gt;) sections to have content that displays only on the template page itself, such as help and usage, but not use it when the template is called. See also [http://meta.wikimedia.org/wiki/Help:Templates#Noinclude.2C_includeonly.2C_and_onlyinclude].



===Conditionals, logic===
So far, it looks like templates very much originate as a hack, with almost no actual capabilities. 

From the pages I've read so far, it seems anything actually useful sits in mediawiki extensions, primarily [http://meta.wikimedia.org/wiki/ParserFunctions ParserFunctions].

==Examples==


===Usable templates in this wiki===
'''&#x7b;&#x7b;comment&#x7d;&#x7d;''' makes things a subtler color {{comment|(like so)}}
 <nowiki>&lt;div style="display:inline; color:#9977aa">{{{1}}}&lt;/div></nowiki>


'''&#x7b;&#x7b;inlinecode&#x7d;&#x7d;''' uses a {{inlinecode|styled monospace for specifying commands or code}} inline. You regularly have to wrap its contents in in a &lt;nowiki> tag to avoid interpretation as template parameters. Defined as something like:
 <span style="white-space:normal;"><nowiki>&lt;div style="display:inline; background-color: #eee; border-top:1px solid #ccc; border-bottom:1px solid #ccc">&lt;tt>{{{1}}}&lt;/tt>&lt;/div></nowiki></span>


'''&#x7b;&#x7b;stub&#x7d;&#x7d;''' and &#x7b;&#x7b;feelfree&#x7d;&#x7d; are boxes with some text and a link, defined using something like:
 <span style="white-space:normal;"><nowiki>{| align=center style="background: #f9f9f9; border: 1px solid #aaa; padding: .2em; margin-bottom: 3px; font-size: 95%; width: auto;"
| style="padding-right: 4px; padding-left: 4px;" | '''This article (or section) is a [[Help:Editing#Templates|stub]].'''&lt;br>It is here because it was planned, and some notes were dropped here. Feel free to add more notes or suggestions, or write an article.
|}</nowiki></span>


'''&#x7b;&#x7b;verify&#x7d;&#x7d;''' just shows '(verify)'. The purpose is to be able to [https://helpful.knobs-dials.com/index.php/Special:WhatLinksHere/Verify search for these markers], which is why it links to a page called [[verify]].
 <nowiki>&lt;em style="color:#aaa">([[verify]])&lt;/em></nowiki>



There are things like:
{{info|&#x7b;&#x7b;info&#x7d;&#x7d;}}

{{confusion|&#x7b;&#x7b;confusion&#x7d;&#x7d;}}

{{warning|&#x7b;&#x7b;warning&#x7d;&#x7d;}}

{{zzz|&#x7b;&#x7b;zzz&#x7d;&#x7d; for relatively boring side information}}

to annotate blocks of text with

=See also=
* http://www.mediawiki.org/wiki/Manual:FAQ
* http://www.mediawiki.org/wiki/Manual:Errors_and_symptoms
<!--
* http://www.mediawiki.org/wiki/Manual:Image_Administration
-->