3 '''tldr''': For GNU/Linux (with a bit of Debian bias), a more concise, holistic and automated install than the official Mediawiki docs. Do some initial configuration then download this page and run it, or execute it as you read.
5 ''' Goals / Why use this guide? '''
7 * Good recommendations. Official docs mostly avoid recommendations among a myriad of possibilities
8 * Closely references & supplements official documentation
9 * Automatic security updates
10 * Explicit automation support wherever practical
11 * Used to setup this site (style is optional)
12 * Support for multiple gnu/linux distros
13 * Holistic scope (backups, server setup), but sections are independent
14 * Code blocks are [https://en.wikipedia.org/wiki/Idempotent idempotent]
15 * Edits to this page are tested on this site and reviewed by the main author.
19 * Self hosting, single GNU/Linux system with root Bash shell
24 Very minor adjustments needed for other distros. Help expand this list.
25 * Mediawiki 1.28, 1.27 support is planned to be re-added.
26 * Debian 8 + backports
30 Pre 5/2016 revisions ran Mediawiki 1.23, tested on Fedora 20 and Ubuntu 14.04.
34 '''Getting a Server & a Domain'''
36 The most common route and the one taken by this site is buying a domain name from a site like namecheap, and a cheap vps from companies like linode or digital ocean. They have good getting started guides which mostly apply beyond their own sites.
40 For debian jessie with backports:
42 # if we have jessie-backports, we need to use it.
43 if ! apt-get install -t jessie-backports certbot python-certbot-apache; then
44 apt-get install certbot python-certbot-apache
48 For other distros, follow instructions at [https://certbot.eff.org/ certbot.eff.org].
52 Setting up email can be an involved process, and this guide assumes that a some program (usually postfix or exim) is implementing a functional sendmail interface. Mediawiki uses email with to send password reminders or notifications, and this guide includes cronjobs for updating mediawiki and doing backups which will send mail in the case of an error. Email is also the recommended way to get notifications of package updates which require manual steps such as restarting of services.
54 If you are not setting up your server to send mail with a program that uses the default sendmail interface, see these pages when you are configuring mediawiki: [[mediawikiwiki:Manual:$wgEnableEmail|Manual:$wgEnableEmail]], [https://www.mediawiki.org/wiki/Configuration_settings#Email_settings Manual:Email_settings], [[mediawikiwiki:Manual:$wgSMTP|Manual:$wgSMTP]]
56 == Setup Guide Configuration ==
59 # Save the code in this section to a file (~/mw_vars is suggested)
60 # Source it at the beginning of scripts containing later commands
61 # Source it from your .bashrc file while you are setting up Mediawiki
63 '''Requires customization:'''
64 <source lang="bash" type="example">
65 # Replace REPLACE_ME as appropriate
67 export mwdescription="REPLACE_ME" # eg. Opinionated Free Software Wiki
69 # username/pass of the first wiki admin user
70 export wikiuser="REPLACE_ME"
71 export wikipass=REPLACE_ME
73 # root & user password for the mysql database
74 export dbpass=REPLACE_ME
76 export mwdomain=REPLACE_ME # domain name. for this site, it's ofswiki.org
78 # customize these questions. Try not to have the answer be a word in the question.
80 if ! grep -Fx '$localSettingsQuestyQuestions = array (' $mwc; then
82 $localSettingsQuestyQuestions = array (
83 "What is the name of the wiki software this site (and wikipedia) uses?" => "Mediawiki",
84 "REPLACE_ME with a question" => "REPLACE_ME with an answer"
90 # The rest of this section will work fine with no changes.
92 # git branch for mediawiki + extensions. See intro for supported versions.
93 # branch names: https://git.wikimedia.org/branches/mediawiki%2Fcore.git
94 export mw_branch=REL1_28
96 # As set by gui installer when choosing cc by sa.
97 export mw_RightsUrl='https://creativecommons.org/licenses/by-sa/4.0/'
98 export mw_RightsText='Creative Commons Attribution-ShareAlike'
99 export mw_RightsIcon='$wgScriptPath/resources/assets/licenses/cc-by-sa.png'
101 # Alphanumeric site name for pywikibot.
102 # Here we use the domain minus the dots, which should work fine without changing.
103 export mwfamily=${mwdomain//./}
104 # install path for mediawiki. This should work fine.
105 export mw=/var/www/$mwdomain/html/w
108 # wiki sender address / wiki & wiki server contact email.
109 # see email section for more info on email
110 export mw_email="admin@$mwdomain"
113 mwc="$mw/LocalSettings.php"
116 == Download this page and run it ==
118 This is an option to do automated setup. Optional code blocks are skipped (they have a bold warning just before them and a tag on the source block). The only important things left after running this are running the automated backup setup code on another machine.
120 ''' Requires manual step: inspect output file: /tmp/mw-setup, then run it'''
121 <source lang="bash" type="example">
122 start=' *<source lang="bash"> *'
124 ruby <<'EOF' | sed -rn "/^$start$/,/^$end$/{s/^$start|$end$/# \0/;p} > /tmp/mw-setup"
126 puts JSON.parse(`curl 'https://ofswiki.org/w/api.php?\
127 action=query&titles=Mediawiki_Setup_Guide&prop=revisions&rvprop=content&\
128 format=json'`.chomp)['query']['pages'].values[0]['revisions'][0]['*']
130 chmod +x /tmp/mw-setup
133 == Required Bash Functions ==
135 Here we define some small useful bash functions. This should be part of the same ~/mw_vars file if you are running the code step by step.
138 # identify if this is a debian based distro
139 isdeb() { command -v apt &>/dev/null; }
140 # tee unique. append each stdin line if it does not exist in the file
144 for line in "${MAPFILE[@]}"; do
145 grep -xFq "$line" "$1" &>/dev/null || tee -a "$1" <<<"$line"
149 # get and reset an extension/skin repository, and enable it
152 local original_pwd="$PWD"
154 local re='[^/]*/[^/]*$' # last 2 parts of path
155 [[ $url =~ $re ]] ||:
156 target=$mw/${BASH_REMATCH[0]}
157 if [[ ! -e $target/.git ]]; then
158 git clone $url $target
160 if ! cd $target; then
161 echo "mw-ext error: failed cd $target";
165 git checkout -qf origin/$mw_branch || git checkout -qf origin/master
173 mw-clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/$ext
174 if [[ -e $mw/extensions/$ext/extension.json ]]; then
175 # new style extension
177 wfLoadExtension( '$ext' );
181 require_once( "\$IP/extensions/$ext/$ext.php" );
185 # --quick is quicker than default flags,
186 # but still add a sleep to make sure everything works right
187 sudo -u $apache_user php $mw/maintenance/update.php -q --quick; sleep 1
191 mw-clone https://gerrit.wikimedia.org/r/p/mediawiki/skins/$skin
192 sed -i --follow-symlinks '/^wfLoadSkin/d' $mwc
193 sed -i --follow-symlinks '/^\$wgDefaultSkin/d' $mwc
195 \$wgDefaultSkin = "${skin,,*}";
196 wfLoadSkin( '$skin' );
198 sudo -u $apache_user php $mw/maintenance/update.php -q --quick; sleep 1
201 if command -v apt &>/dev/null; then
209 == Install Mediawiki Dependencies ==
211 The best way to get core dependencies is to install the mediawiki package itself. Nothing about it will get in the way of using a version from upstream.
213 [[mediawikiwiki:Main Page|Mediawiki Main Page]]: the beginning of the official docs.
215 [[mediawikiwiki:Manual:Installation_requirements|Manual:Installation_requirements]]: Overview of installation requirements.
217 Note, this guide needs a little adjustment before it will work with php7.0: make sure settings are still valid, update ini path.
222 # From here on out, exit if a command fails.
223 # This will prevent us from not noticing an important failure.
224 # We recommend setting this for the entire installation session.
225 # If you are running commands interactively, it might be best to
226 # put it in your ~/.bashrc temporarily.
228 trap 'echo "$0:$LINENO:error: \"$BASH_COMMAND\" returned $?" >&2' ERR
233 # https://www.mediawiki.org/wiki/Manual:Running_MediaWiki_on_Ubuntu
235 DEBIAN_FRONTEND=noninteractive apt-get install -y imagemagick curl
236 if apt-get install -s mediawiki &>/dev/null; then
238 if apt-get install -s php7.0-apcu &>/dev/null; then
241 # mediawiki is packaged in jessie backports & stretch
242 DEBIAN_FRONTEND=noninteractive apt-get -y install $apcu mediawiki
244 # https://www.mediawiki.org/wiki/Manual:Installation_requirements
245 if apt-get install -s php7.0 &>/dev/null; then
246 # note, 7.0 is untested by the editor here, since it's not
247 # available in debian 8. it's listed as supported
248 # in the mediawiki page.
249 # noninteractive to avoid mysql password prompt.
250 DEBIAN_FRONTEND=noninteractive apt-get install -y apache2 \
251 default-mysql-server \
252 php7.0 php7.0-mysql libapache2-mod-php7.0 php7.0-xml \
253 php7.0-apcu php7.0-mbstring
255 # note: mbstring is recommended, but it's not available for php5 in
257 DEBIAN_FRONTEND=noninteractive apt-get install -y apache2 \
258 default-mysql-server \
259 php5 php5-mysql libapache2-mod-php5 php5-apcu
262 service apache2 restart
265 # fedora deps are missing a database, so some is translated from debian packages
266 yum -y install mediawiki ImageMagick php-mysqlnd php-pecl-apcu mariadb-server
268 systemctl restart mariadb.service
269 systemctl enable mariadb.service
270 systemctl enable httpd.service
271 systemctl restart httpd.service
275 # skip if we already set the root pass and are on pre-debian 9.
276 if ! echo exit|mysql -uroot "-p$dbpass"; then
277 # Note: we set a root password here, but in debian 9+, it is ignored;
278 # only the local user root can login, and any password is accepted.
279 # We answer these interactive prompts:
280 # Enter current password for root (enter for none):
281 # Set root password? [Y/n]
283 # Re-enter new password:
284 # Remove anonymous users? [Y/n]
285 # Disallow root login remotely? [Y/n]
286 # Remove test database and access to it? [Y/n]
287 # Reload privilege tables now? [Y/n]
288 # Note, I had 1 less newline at the start when doing ubuntu 14.04,
289 # compared to debian 8, so can't say this is especially portable.
290 echo -e "\n\n$dbpass\n$dbpass\n\n\n\n\n" | mysql_secure_installation
292 mysql -uroot "-p$dbpass" <<EOF
293 GRANT ALL PRIVILEGES ON my_wiki.* TO 'wikiuser'@'localhost' IDENTIFIED BY '$dbpass';
298 '''Skippable notes'''
301 php[5]-mysqlnd is a faster mysql driver package, but the default in debian php-mysql, appparently because some non-mediawiki packages are not compatible with it. If you run into this issue, simply use the php-mysql package.
304 Additional packages rational
305 * ImageMagick is [https://www.mediawiki.org/wiki/Manual:Image_administration#Image_thumbnailing recommended].
306 * Gui install and [[mediawikiwiki:Manual:Cache]] recomend the apc package.
307 * Clamav for virus scanning of uploads is mentioned in the mediawiki manual. However, wikipedia doesn't seem to do it, so it doesn't seem like it's worth bothering. It also makes uploading a set of images take twice as long on broadband.
309 == Install Mediawiki ==
312 Here, we [[mediawikiwiki:Download_from_Git]], or reset our installation if it is already there, and create the wiki database. [[mediawikiwiki:Manual:Installing_MediaWiki]]
317 # this will just fail if it already exists which is fine
318 if [[ ! -e .git ]]; then
319 git clone https://gerrit.wikimedia.org/r/p/mediawiki/core.git .
321 # to see available branches: https://www.mediawiki.org/wiki/Version_lifecycle
324 git checkout -f origin/$mw_branch
326 # apply librejs patch
327 curl "https://iankelling.org/git/?p=mediawiki-librejs-patch;a=blob_plain;f=mediawiki-1.28-librejs.patch;hb=HEAD" | patch -r - -N -p1
328 # Get the php libraries wmf uses. Based on:
329 # https://www.mediawiki.org/wiki/Download_from_Git#Fetch_external_libraries
330 if [[ ! -e vendor/.git ]]; then
331 git clone https://gerrit.wikimedia.org/r/p/mediawiki/vendor.git
334 git checkout -f origin/$mw_branch
337 # Drop any previous database which may have been installed while testing.
338 # If upgrading, we should have a db backup which will get restored.
339 # https://www.mediawiki.org/wiki/Manual:Upgrading
340 mysql -uroot "-p$dbpass" <<'EOF' ||:
341 drop database my_wiki;
344 php $mw/maintenance/install.php --pass $wikipass --scriptpath /w \
345 --dbuser wikiuser --dbpass $dbpass "$mwdescription" "$wikiuser"
347 # lock down the wiki to only the initial owner until anti-spam measures are put in place
348 # limit edits to registered users
349 $wgGroupPermissions['*']['edit'] = false;
350 # don't allow any account creation
351 $wgGroupPermissions['*']['createaccount'] = false;
356 Note: When testing, you may need to clear the apc cache to see changes take effect in the browser. Simplest solution is
357 just restart apache. http://stackoverflow.com/questions/911158/how-to-clear-apc-cache-entries
359 ''' Skippable Notes'''
361 If we wanted to reset our installation, but leave the extension repositories alone, alter the command above to be <code>git clean -fxd</code>
363 '''Rational for choosing git sources'''
365 Upstream vs distro packages. Upstream is responsive, and it's distributed within a single directory, so packaging does not integrate with the distro's filesystem. The only potential value would be less bugs by using stable versions, but we choose not to make that tradeoff.
367 Why use git over zip file releases? Mediawiki supports git usage through release branches which get post-release fixes. This means we can auto-update, get more granular fixes, easier to manage updates, and rollbacks.
369 == Configure Apache ==
371 Note, non-debian based installs: modify instructions below to use /etc/httpd/conf.d/$mwdomain.conf, and don't run a2ensite.
373 I use scripts I maintains separately to setup Let's Encrypt certificates and apache config: (url pending).
375 If you are doing a test setup on your local machine, you can make your domain resolve to your local test installation, then remove it later when you are done. Note, you will need non-local site to get Let's Encrypt certificates, and then transfer them locally, or disable ssl from the apache config (neither is covered here) and replace all instances of https in these instructions with http. Another option is to get a cheap 2 dollar domain for your test site.
377 '''Not for production:'''
378 <source lang="bash" type="example">
379 teeu /etc/hosts<<<"127.0.0.1 $mwdomain"
382 To not use my scripts, and still use Let's Encrypt: follow this doc page: https://letsencrypt.org/getting-started/. It's a little long winded, so I would boil it down to this:
384 '''Optional & requires additional steps:'''
385 <source lang="bash" type="example">
386 git clone https://github.com/certbot/certbot
388 ./certbot-auto apache
389 cd /etc/apache/sites-available
390 mv 000-default-le-ssl.conf $mwdomain.conf
391 rm ../sites-enabled/000-default-le-ssl.conf
392 # edit $mwdomain.conf, so documentroot is /var/www/$mwdomain/html
393 # and ServerName is $mwdomain
394 a2ensite $mwdomain.conf
396 Then, copy the input to apache-site below and insert it into the apache config.
398 Here, we use some scripts automate setting up the Let 's Encrypt cert and
406 # for me, this repo is on the same server and apache needs a sec after restarting
408 git clone https://iankelling.org/git/basic-https-conf
410 ServerAdmin $mw_email
412 # make the site's root url go to our main page
413 RewriteRule ^/?wiki(/.*)?\$ %{DOCUMENT_ROOT}/w/index.php [L]
414 # use short urls https://www.mediawiki.org/wiki/Manual:Short_URL
415 RewriteRule ^/*\$ %{DOCUMENT_ROOT}/w/index.php [L]
417 find -L $(readlink -f $mw) -name .htaccess \
418 | while read line; do
419 echo -e "<Directory ${line%/.htaccess}>\n $(< $line)\n</Directory>";
421 } | basic-https-conf/web-conf -r ${mw%/*} - apache2 $mwdomain
426 Now mediawiki should load in your browser at $mwdomain .
428 Allow proper search bots and internet archiver bots, via [[Mediawiki:Robots.txt]],
429 and install the default skin.
432 dd of=$mw/../robots.txt <<'EOF'
435 User-agent: ia_archiver
441 '''Skippable Notes'''
443 This section assumes we are redirecting www to a url without www.
445 [http://httpd.apache.org/docs/current/howto/htaccess.html Apache recommends] moving .htaccess rules into it's config for performance. So we look for .htaccess files from mediawiki and copy their contents into this config. In modern apache versions, we would have to explicitly set options like AllowOverride to allow .htaccess files to take effect.
447 == Mediawiki Settings ==
449 Overall reference: [[mediawikiwiki:Manual:Configuration_settings]].
451 Settings which the gui setup prompts for but aren't set by the automated install script.
454 \$wgServer = "https://$mwdomain";
455 \$wgDBserver = "localhost";
456 \$wgRightsUrl = "$mw_RightsUrl";
457 \$wgRightsText = "$mw_RightsText";
458 \$wgRightsIcon = "$mw_RightsIcon";
461 Settings asked by the gui setup which are different than the install script defaults. They different because the defaults are the most compatible and unobtrusive.
464 \$wgPasswordSender = "$mw_email";
465 \$wgEmergencyContact = "$mw_email";
466 \$wgEnotifUserTalk = true; # UPO
467 \$wgEnotifWatchlist = true; # UPO
468 \$wgMainCacheType = CACHE_ACCEL;
469 \$wgEnableUploads = true;
470 \$wgUseInstantCommons = true;
478 # from https://www.mediawiki.org/wiki/Manual:Short_URL
479 $wgArticlePath = "/wiki/$1";
481 # https://www.mediawiki.org/wiki/Manual:Combating_spam
482 # check that url if our precautions don't work
483 # not using nofollow is good practice, as long as we avoid spam.
484 $wgNoFollowLinks = false;
485 # Allow user customization.
486 $wgAllowUserCss = true;
487 # use imagemagick over GD
488 $wgUseImageMagick = true;
489 # manual says this is not production ready, I think that is mostly
490 # because they are using MobileFrontend extension instead, which gives
491 # an even cleaner more minimal view, I plan to try setting it up
492 # sometime but this seems like a very nice improvement for now.
493 $wgVectorResponsive = true;
497 # https://www.mediawiki.org/wiki/Manual:Configuring_file_uploads
498 # Increase from default of 2M to 100M.
499 # This will at least allow high res pics etc.
500 php_ini=$(php -r 'echo(php_ini_loaded_file());')
501 sed -i --follow-symlinks 's/^\(upload_max_filesize\|post_max_size\)\b.*/\1 = 100M/' $php_ini
503 service apache2 restart
505 systemctl restart httpd.service
508 # if you were to install as a normal user, you would need this for images
509 # sudo usermod -aG $apache_user $USER
511 # this doesn't propogate right away
512 chgrp -R $apache_user $mw/images
513 chmod -R g+w $mw/images
516 Style settings. Omit to use a different style.
520 #$wgFooterIcons = null;
522 # Make the toolbox go into the drop down.
524 if ! git remote show ian-kelling &>/dev/null; then
525 git remote add ian-kelling https://iankelling.org/git/mediawiki-sidebar-patch
527 git fetch ian-kelling
528 git checkout ian-kelling/${mw_branch}-toolbox-in-dropdown
531 == Install and Configure Mediawiki Extensions ==
533 When installing extensions on a wiki with important content, backup first as a precaution.
535 ''' Extensions with no configuration needed '''
541 | [[mediawikiwiki:Extension:Cite|Extension:Cite]]
542 | Have references in footnotes*
544 | [[mediawikiwiki:Extension:CiteThisPage|Extension:CiteThisPage]]
545 | Ability to generate citations to pages in a variety of styles*
547 | [[mediawikiwiki:CheckUser|Extension:CheckUser]]
548 | Get ip addresses from inside mediawiki so you can ban users''
550 | [[mediawikiwiki:Extension:CSS|Extension:CSS]]
551 | Allows CSS stylesheets to be included in specific articles
553 | [[mediawikiwiki:Extension:Echo|Extension:Echo]]
554 | Notification subsystem for usage by other extensions
556 | [[mediawikiwiki:Extension:Gadgets|Extension:Gadgets]]
557 | UI extension system for users*
559 | [[mediawikiwiki:Extension:ImageMap|Extension:ImageMap]]
560 | Links for a region of an image*
562 | [[mediawikiwiki:Extension:Interwiki|Extension:Interwiki]]
563 | Tool for nice links to other wikis*
565 | [[mediawikiwiki:Extension:News|Extension:News]]
566 | Embed or rss recent changes
568 | [[mediawikiwiki:Extension:Nuke|Extension:Nuke]]
569 | Mass delete of pages, in the case of spam*
571 | [[mediawikiwiki:Extension:ParserFunctions|Extension:ParserFunctions]]
572 | Useful for templates*
574 | [[mediawikiwiki:Extension:Poem|Extension:Poem]]
575 | Useful for formatting things various ways*
577 | [[mediawikiwiki:Extension:Renameuser|Extension:Renameuser]]
578 | Allows bureaucrats to rename user accounts*
580 | [[mediawikiwiki:Extension:SyntaxHighlight_GeSHi|Extension:SyntaxHighlight_GeSHi]]
581 | Source code highlighting*
583 | [[mediawikiwiki:Extension:Variables|Extension:Variables]]
584 | Define per-page variables
587 <nowiki>*</nowiki> = Comes with the MediaWiki default download.
590 mw-ext Cite CiteThisPage CheckUser CSS Echo Gadgets ImageMap Interwiki News \
591 Nuke ParserFunctions Poem Renameuser SyntaxHighlight_GeSHi Variables
595 ''' [[mediawikiwiki:Extension:AntiSpoof|Extension:AntiSpoof]]: Disallow usernames with unicode trickery to look like existing names'''
599 # recommended setup script to account for existing users
600 sudo -u $apache_user php $mw/extensions/AntiSpoof/maintenance/batchAntiSpoof.php
604 '''[[mediawikiwiki:Extension:Wikidiff2|Extension:Wikidiff2]]: Faster and international character supported page diffs'''
606 I used packaged version since this is a c++ and probably not very tied to the Mediawiki version. This isn't packaged in fedora, haven't gotten around to testing and adding the code to compile it for fedora.
609 apt-get -y install php-wikidiff2
611 $wgExternalDiffEngine = 'wikidiff2';
613 dir=$(dirname $(php -r 'echo(php_ini_loaded_file());'))/../apache2/conf.d
614 ln -sf ../../mods-available/wikidiff2.ini $dir
615 service apache2 restart
620 ''' [[mediawikiwiki:Extension:Math|Extension:Math]] Display equations'''
624 # php5-curl according to Math readme
627 if ! apt-get -s install $curl_pkg &>/dev/null; then
630 apt-get -y install latex-cjk-all texlive-latex-extra texlive-latex-base \
631 ghostscript imagemagick ocaml $curl_pkg make
633 # todo, php5-curl equivalent on fedora
634 yum -y install texlive-cjk ghostscript ImageMagick texlive ocaml
636 service apache2 restart
638 cd $mw/extensions/Math/math; make # makes texvc
639 cd $mw/extensions/Math/texvccheck; make
642 # Enable MathJax as rendering option
643 $wgUseMathJax = true;
644 # Enable LaTeXML as rendering option
645 $wgMathValidModes[] = 'latexml';
646 # Set LaTeXML as default rendering option, because it is nicest
647 $wgDefaultUserOptions['math'] = 'latexml';
651 '''Skippable notes'''
653 There is no current list of package depencies so I took dependencies from mediawiki-math package in Debian 7. Fedora didn't have a mediawik math package, so I just translated from debian. Ocaml is for math png rendering, as backup option to the nicer looking LatexML and MathJax. Debian has texvc package, but it didn't work right for me, plus it required additional configuration in mediawiki settings.
656 ''' [[mediawikiwiki:Extension:SpamBlacklist|Extension:SpamBlacklist]]: Import/create IP blacklists, mainly for spam'''
658 Comes with MediaWiki.
662 if ! grep -F '$wgSpamBlacklistFiles = array(' $mwc &>/dev/null; then
664 $wgEnableDnsBlacklist = true;
665 $wgDnsBlacklistUrls = array( 'xbl.spamhaus.org', 'dnsbl.tornevall.org' );
667 ini_set( 'pcre.backtrack_limit', '10M' );
668 $wgSpamBlacklistFiles = array(
669 "[[m:Spam blacklist]]",
670 "http://en.wikipedia.org/wiki/MediaWiki:Spam-blacklist"
676 ''' [[mediawikiwiki:Extension:TitleBlacklist|Extension:TitleBlacklist]]: Anti-spam '''
678 Comes with Mediawiki.
681 mw-ext TitleBlacklist
682 if ! grep -F '$wgTitleBlacklistSources = array(' $mwc &>/dev/null; then
684 $wgTitleBlacklistSources = array(
687 'src' => 'MediaWiki:Titleblacklist',
691 'src' => 'http://meta.wikimedia.org/w/index.php?title=Title_blacklist&action=raw',
698 ''' [[mediawikiwiki:Extension:WikiEditor|Extension:WikiEditor]]: Editing box extras and a fast preview tab '''
700 Comes with MediaWiki.
705 # Enable Wikieditor by default
706 $wgDefaultUserOptions['usebetatoolbar'] = 1;
707 $wgDefaultUserOptions['usebetatoolbar-cgd'] = 1;
709 # Display the Preview and Changes tabs
710 $wgDefaultUserOptions['wikieditor-preview'] = 1;
714 ''' [[mediawikiwiki:CategoryTree|Extension:CategoryTree]]: Enables making nice outlines of pages in a category'''
718 # Mediawiki setting dependency for CategoryTree
723 ''' [[mediawikiwiki:Extension:AbuseFilter|Extension:AbuseFilter]]: Complex abilities to stop abuse '''
725 Used by big wiki sites. As a smaller site, we won't use it much, but it's good to have. It's page suggests a few defaults:
729 $wgGroupPermissions['sysop']['abusefilter-modify'] = true;
730 $wgGroupPermissions['*']['abusefilter-log-detail'] = true;
731 $wgGroupPermissions['*']['abusefilter-view'] = true;
732 $wgGroupPermissions['*']['abusefilter-log'] = true;
733 $wgGroupPermissions['sysop']['abusefilter-private'] = true;
734 $wgGroupPermissions['sysop']['abusefilter-modify-restricted'] = true;
735 $wgGroupPermissions['sysop']['abusefilter-revert'] = true;
739 '''[[mediawikiwiki:Extension:ConfirmEdit|Extension:ConfirmEdit]]: Custom Captcha.'''
741 Uses captchaArray defined in mw_vars. Comes with MediaWiki.
747 wfLoadExtension( 'ConfirmEdit/QuestyCaptcha' );
748 $wgCaptchaClass = 'QuestyCaptcha';
749 # only captcha on registration
750 $wgGroupPermissions['user' ]['skipcaptcha'] = true;
751 $wgGroupPermissions['autoconfirmed']['skipcaptcha'] = true;
753 if ! grep -Fx 'foreach ( $localSettingsQuestyQuestions as $key => $value ) {' $mwc; then
755 foreach ( $localSettingsQuestyQuestions as $key => $value ) {
756 $wgCaptchaQuestions[] = array( 'question' => $key, 'answer' => $value );
762 Enable account creation that we initially disabled.
764 sed -i --follow-symlinks "/\\\$wgGroupPermissions\\['\\*'\\]\\['createaccount'\\] = false;/d" $mwc
767 == Additional Configuration with Pywikibot ==
769 There are quite a few [[mediawikiwiki:Help:Namespaces|special pages]] which act like variables to configure special wiki content and style. A big part of this wiki's style is configured in this section. We use Pywikibot to automate editing those pages.
772 '''Pywikibot Install'''
774 [[mediawikiwiki:Manual:Pywikibot/Installation|Manual:Pywikibot/Installation]]
778 if [[ ! -e ~/pywikibot/.git ]]; then
779 git clone --recursive \
780 https://gerrit.wikimedia.org/r/pywikibot/core.git ~/pywikibot
789 '''Pywikibot Configuration'''
791 Relevent docs: [[mediawikiwiki:Manual:Pywikibot/Use_on_non-WMF_wikis|Manual:Pywikibot/Use_on_non-WMF_wikis]], [[mediawikiwiki:Manual:Pywikibot/Quick_Start_Guide|Manual:Pywikibot/Quick_Start_Guide]]
796 dd of=user-config.py <<EOF
798 usernames["$mwfamily"]['en'] = u'$wikiuser'
800 console_encoding = 'utf-8'
801 password_file = "secretsfile"
804 dd of=secretsfile <<EOF
805 ("$wikiuser", "$wikipass")
808 # it won't overrwrite an existing file. Remove if if one exists
809 rm -f pywikibot/families/${mwfamily}_family.py
811 apt-get install -y python-requests
813 yum -y install python-requests
816 python generate_family_file.py https://$mwdomain/wiki/Main_Page "$mwfamily"
818 # Note, this needed only for ssl site
819 tee -a pywikibot/families/${mwfamily}_family.py<<'EOF'
820 def protocol(self, code):
826 '''Pywikibot Script'''
828 This will take a full minute or so because the bot waits a few seconds between edits. Useful doc: [[mediawikiwiki:Pywikipediabot/Create_your_own_script]].
833 dd of=scripts/${mwfamily}_setup.py<<EOF
837 site = pywikibot.Site()
839 page = pywikibot.Page(site, p)
841 #force is for some anti-bot thing, not necessary in my testing, but might as well include it
842 page.save(force=True)
844 # Small/medium noncommercial wiki should be fine with no privacy policy
845 # based on https://www.mediawiki.org/wiki/Manual:Footer
846 x("MediaWiki:Privacy")
848 # licenses for uploads. Modified from the mediawiki's wiki
849 x("MediaWiki:Licenses", u"""* Same as this wiki's text (preferred)
850 ** CC BY-SA or GFDL| Creative Commons Attribution ShareAlike or GNU Free Documentation License
852 ** Unknown_copyright|I don't know exactly
853 ** PD|PD: public domain
854 ** CC BY|Creative Commons Attribution
855 ** CC BY-SA|Creative Commons Attribution ShareAlike
856 ** GFDL|GFDL: GNU Free Documentation License
857 ** GPL|GPL: GNU General Public License
858 ** LGPL|LGPL: GNU Lesser General Public License""")
859 x("MediaWiki:Copyright", '$mw_license')
860 x("MediaWiki:Mainpage-description", "$mwdescription")
864 # The rest of the settings are for the site style
866 # Remove various clutter
867 x("MediaWiki:Lastmodifiedat")
868 x("MediaWiki:Disclaimers")
869 x("MediaWiki:Viewcount")
870 x("MediaWiki:Aboutsite")
871 # remove these lines from sidebar
872 # ** recentchanges-url|recentchanges
873 # ** randompage-url|randompage
875 x("MediaWiki:Sidebar", """* navigation
876 ** mainpage|mainpage-description
882 # helpfull doc: https://www.mediawiki.org/wiki/Manual:Interface/Sidebar
883 x("mediawiki:Common.css", """/* adjust sidebar to just be home link and up top */
884 /* adjust sidebar to just be home link and up top */
885 /* panel width increased to fit full wiki name. */
886 /* selectors other than final id are for increasing priority of rule */
887 div#mw-panel { top: 10px; padding-top: 0em; width: 20em }
888 div#footer, #mw-head-base, div#content { margin-left: 1em; }
889 #left-navigation { margin-left: 1em; }
892 /* logo, and toolbar hidden */
893 #p-logo, div#mw-navigation div#mw-panel #p-tb {
897 div#mw-content-text {
903 # this can spam a warning, so uniq it
904 python pwb.py ${mwfamily}_setup |& uniq
908 ''' Skippable Notes '''
910 The docs suggest manually entering the pass with python pwb.py login.py, then it should stay logged in. That didn't work for me, and anyways, we automation, so we use secrets file method.
912 Family name, and all its duplicattions documented as supposed to be $wgSitename, but it works fine using any name.
914 == Automatic Backups ==
916 Here we will have a daily cronjob where a backup host sshs to the mediawiki host, makes a backup then copies it back. Copy ~/mw_vars to the backup host at /root/mw_vars. Setup passwordless ssh from the backup host to the mediawiki host. Then run this code on the backup host. This will make a versioned backup of the wiki to ~/backup.
918 <source lang="bash" type="backup">
919 backup_script=/etc/cron.daily/mediawiki_backup
920 sudo dd of=$backup_script <<'EOFOUTER'
922 # if we get an error, keep going but return it at the end
924 trap 'last_error=$?' ERR
926 # No strict because the host is likely not named the same as
928 ssh="ssh -oStrictHostKeyChecking=no"
929 logfile=/var/log/${mwdomain}_backup.log
931 echo "#### starting backup at $(date) ####"
932 $ssh root@$mwdomain <<ENDSSH
935 \$wgReadOnly = 'Dumping Database, Access will be restored shortly';
937 mkdir -p ~/wiki_backups
938 mysqldump -p$dbpass --default-character-set=binary my_wiki > ~/wiki_backups/wiki_db_backup
939 sed -i '\$ d' $mwc # delete read only setting
941 # add no strict option to the defaults
943 rdiff() { rdiff-backup --remote-schema "$ssh -C %s rdiff-backup --server" "$@"; }
945 rdiff root@$mwdomain::/root/wiki_backups ~/backup/${mwdomain}_wiki_db_backup
946 rdiff root@$mwdomain::$mw ~/backup/${mwdomain}_wiki_file_backup
948 echo "=== ending backup at $(date) ===="
950 if [[ $last_error != 0 ]]; then
951 echo "backup for $mwdomain failed. See $logfile"
956 sudo chmod +x $backup_script
959 '''Optional & requires additional steps'''
961 If you are like most people and don't use the old-school mail spool, setup the backup system to send mail externally so you are notified if it fails. For examples of how to do this, [http://unix.stackexchange.com/questions/36982/can-i-set-up-system-mail-to-use-an-external-smtp-server stackoverflow], [https://iankelling.org/git/?p=ian-specific/distro-setup;a=blob;f=mail-setup;hb=HEAD script I use].
963 == Restoring Backups ==
965 '''Whenever you implement a backup system, you should test that restoring the backup works.'''
967 You ''should'' be able to restore your wiki to a new machine by repeating all install steps, then restoring the database and the images directory. I've done this many times. However, we backup the entire Mediawiki directory in case you forget to record a step or some corner case happens. Since most people don't record the steps they took to setup Mediawiki, this is also the officially recommended method. In the code below we restore only the database and images folder from the full backup. You can try this after setting up a wiki from scratch. If it doesn't work, you know your fresh setup is not replicating your backed up wiki correctly. In that case, you can fall back to doing a full restore by copying the full directory instead of just the images. See [[mediawikiwiki:Manual:Restoring a wiki from backup]] if you run into any problems.
969 To test a backup restore:
970 # Do a backup of your wiki with some content in it, as described in the previous section
971 # Move your mediawiki install directory, or setup Mediawiki on a new machine
972 # Re-execute the mediawiki install steps
973 # Change REPLACE_ME in the code below (as in the backup section so you get the right variables),
974 # Execute the code on the backup machine.
977 <source lang="bash" type="example">
980 restore="rdiff-backup --force -r now"
981 $restore ~/backup/${mwdomain}_wiki_file_backup /tmp/wiki_file_restore
982 $restore ~/backup/${mwdomain}_wiki_db_backup /tmp/wiki_db_restore
983 o=-oStrictHostKeyChecking=no
984 scp $o -r /tmp/wiki_file_restore/images/* root@$mwdomain:$mw/images
985 scp $o -r /tmp/wiki_db_restore root@$mwdomain:/tmp
986 ssh $o root@$mwdomain <<EOF
988 chmod -R g+w $mw/images
989 chgrp -R www-data $mw/images
990 mysql -uroot "-p$dbpass" my_wiki < /tmp/wiki_db_restore/wiki_db_backup
991 php $mw/maintenance/update.php
995 Then browse to your wiki and see if everything appears to work.
999 Subscribe to get release and security announcements [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki-announce].
1001 For updates, we simply git pull all the repos, then run the maintenance script. This should be done after a backup. We recommend automatic updates to get security fixes and since not much is changing on the release branch. In this example, we update at 5 am daily (1 hour after the automatic backup example).
1003 Major version upgrades should be done manually, and it is recommended to use a new installation directory and the same procedure as for backup & restore. Official reference: [[mediawikiwiki:Manual:Upgrading|Manual:Upgrading]]
1005 Minor updates script:
1006 <source lang="bash">
1007 s=/etc/cron.daily/mediawiki_update
1014 [[ -d $dir ]] || return 1
1016 branch=$(git describe --all)
1017 branch=${branch#remotes/}
1019 new_head=$(git rev-parse $branch)
1020 log=$(git log HEAD..$new_head)
1021 if [[ ! $log ]]; then
1026 git checkout -qf $new_head
1030 for dir in extensions/* skins/* vendor; do
1034 curl "https://iankelling.org/git/?p=mediawiki-librejs-patch;a=blob_plain;f=mediawiki-1.28-librejs.patch;hb=HEAD" | patch -r - -N -p1
1036 php $mw/maintenance/update.php -q --quick
1041 == Upgrading Major Versions ==
1043 Reference documentation is at [[mediawikiwiki:Manual:Upgrading]]
1047 # Read the "Upgrade notices for MediaWiki administrators" on the upgrade version and any skipped versions at [[mediawikiwiki:Version_lifecycle]].
1048 # Setup a blank test wiki with the new version.
1049 # Backup the old database, restore it to the new wiki, run php maintenance/update.php.
1050 # If everything looks good, repeat and replace the old wiki with the new one.
1054 There is a balance between effective anti-spam measures and blocking/annoying contributors. Mediawiki documentation on how to combat spam, is not very good, but it has improved over time: [https://www.mediawiki.org/wiki/Manual:Combating_spam manual: Combating Spam]. It's possible for a spammer to quickly make thousands of edits, and there is no good documentation on purging lots of spam, so you should have a good strategy up front. My current strategy is 3 fold, and is limited to small/medium wiki's:
1056 * Find new spam quickly, revert it & ban the user.
1057 ** Watch, and get notified of changes on all primary content pages: Special:Preferences, Bottom of the page, set an email address, then turn on "Email me also for minor edits of pages and files."
1058 ** Use a rss/atom feed reader, and subscribe to recent changes across the wiki. Newer browsers have an rss feed subscribe button, you can click after going to Special:RecentChanges. If that is not available, you can construct the proper url based on [https://meta.wikimedia.org/wiki/Help:Recent_changes#Web_feed these instructions].
1059 * Require registration to edit, and a custom captcha question on registration.
1060 * Install all non-user inhibiting anti-spam extensions / settings that take a reasonable amount of time to figure out.
1062 == Choosing Extensions ==
1064 Mediawiki.org has pages for ~5200 extensions. Mediawiki maintains ~700 extensions [http://git.wikimedia.org/tree/mediawiki%2Fextensions.git in it's git repo]. Wikipedia uses [https://en.wikipedia.org/wiki/Special:Version over 100 extensions]. Major distributors package [[mediawikiwiki:Comparison_of_extensions_in_distributions| ~36 extensions]]. We looked closely at the distributor's and briefly at the Mediawiki repo extensions. We haven't found any other useful list or recommendations.
1066 Here are brief descriptions of extensions that are part of distributions and why they were rejected for this wiki.
1068 {| class="wikitable"
1070 | '''Footnote''' || deprecated in newer versions
1072 | '''InputBox''' || Add html forms to pages. Can't imagine using it. Would install if I did.
1074 | '''LocalisationUpdate'''|| update localization only. I'm fine updating all of mediawiki, there aren't many updates.
1076 | '''NewestPages''' || A page creation history that doesn't expire like recent-changes. Meh
1078 | '''NewUserNotif''' || Send me a notification when a user registers. Seems like an excessive notification.
1080 | '''Openid''' || Poor UI. 2 pages & 2 links <login> <login with openid> which is confusing & ugly.
1082 | '''Pdfhandler''' || Gallery of pages from a pdf file. Can't imagine using it. Would install if I did.
1084 | '''RSSReader''' || Embed an rss feed. Can't imagine using it. Would install if I did.
1086 | '''Semantic''' || Seems like a lot of trouble around analyzing kinds of data which my wiki will not have.
1088 | '''Validator''' || dependency of of semantic
1094 ''' Web Analytics Software '''
1096 I do not recommend using google analytics: it's proprietary software and gives private information of your website visitors to google for them to make money. Piwik has the best features and I recommend it, but I use goaccess because it is simpler to manage and good enough.
1098 ''' Mediawiki Documentation Quality '''
1100 Overall the documentation is good, but like wikipedia, it depends.
1102 The closer a topic is to core functionality and commonly used features, the better the documentation is likely to be. Wikimedia Foundation (WMF) has a competing priority of being a good upstream to mediawiki users and being good for their own sites. That, plus the multitude of unconnected extension developers, and official documentation is sometimes neglected in favor of bug reports, readme files, comments, code, and unpublished knowledge. User's documentation edits vary in quality, and often aren't reviewed by anyone. If you run into an issue, try viewing/diffing the most recent version of a page by the last few editors.
1104 One issue is that mediawiki.org needs a lot of organizing, deleting, and verifying of material, and that is relatively unpopular, tedious, and sometimes difficult work. The discussion pages of mediawiki.org are a wasteland of unanswered questions and outdated conversations, which is [https://www.mediawiki.org/wiki/Help:Talk_pages poor form] for a wiki. However, if you communicate well, you can get great help from their [https://www.mediawiki.org/wiki/Communication support forum, irc, and mailing list].
1107 '''Bash here documents, EOF vs 'EOF' '''
1109 Here documents are used throughout this page, some people may not be aware of a small but important syntax. When the delimiter is quoted, as in <<'EOF', then the contents of the here document are exactly verbatim. Otherwise $ and ` are expanded as in bash, and must be escaped by prefixing them with \, which itself must then also be escaped to be used literally.
1112 ''' Mediawiki automation tools survey 7/2014 '''
1115 * https://github.com/ianweller/mw
1116 * http://search.cpan.org/~markj/WWW-Mediawiki-Client/bin/mvs
1117 * https://github.com/alexz-enwp/wikitools 3000 lines of code, no response to a bug reports in 2/2014
1119 Getting basic maintenance
1120 * https://github.com/mwclient/mwclient 2000 lines of code
1122 Actively developed, used by wikimedia foundation a lot.
1123 * [[mediawikiwiki:Manual:Pywikibot]]
1126 ''' Troubleshooting Errors '''
1128 If mediawiki fails to load, or shows an error in the browser, enable some settings and it will print much more useful information. [[mediawikiwiki:Manual:How to debug]]
1132 This page and this wiki is licensed under cc-by-sa 4.0.
1133 This means the code is compatible with gplv3.
1135 == todo list for this page ==
1137 * Get Visual editor extension.
1138 * Don't require registration for edits
1139 * Take a look at the new debian mediawiki package's apache conf
1140 * For perf, translate extensions allow/deny directives, and set AllowOverride None in apache.conf