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 * Explicit automation support wherever practical
10 * Used to setup this site (style optional)
11 * Contributions welcome and will be updated/tested on this very site!
12 * Support for multiple linux distros
13 * Holistic scope (backups, server setup), but sections stand on their own
14 * Explicit support for production & local testing instance. Additions for production like https and web analytics.
15 * Edits to this page are closely monitored by the original author.
19 * Self hosting, single Linux system with Bash shell
20 * Root shell is assumed throughout
21 * Code blocks are [https://en.wikipedia.org/wiki/Idempotent idempotent]
25 Very minor adjustments needed for other distros. Help expand this list.
28 * Debian testing (tested Aug 7, 2016)
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 Setting up email can be an involved process. Mediawiki is perfectly happy to disable email with 1 setting (no password reminders or notifications), but it is a nice feature to have. You could run your own mail server (on the mediawiki server, or elsewhere), or use one of many services which sends mail for very cheap, or free within limits (popular examples [http://www.mailgun.com/ mailgun], [https://mandrillapp.com/ mandrill], [http://www.mailjet.com/pricing mailjet], [https://aws.amazon.com/ses/ aws]), or connect to a full featured send/receive mail provider like [https://fastmail.com fastmail] (this server is setup that way). How we did that is for a future wiki page.
42 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]]
44 == Setup Guide Configuration ==
47 # Save the code in this section to a file (~/mw_vars is suggested)
48 # Source it at the beginning of scripts containing later commands
49 # Source it from your .bashrc file while you are setting up Mediawiki
51 '''Requires customization:'''
52 <source lang="bash" type="example">
53 # Replace REPLACE_ME as appropriate
55 export mwdescription="REPLACE_ME" # eg. Opinionated Free Software Wiki
57 # username/pass of the first wiki admin user
58 export wikiuser="REPLACE_ME"
59 export wikipass=REPLACE_ME
61 # root password for the mysql database
62 export dbpass=REPLACE_ME
64 # git branch for mediawiki + extensions.
65 # This guide has only been tested with 1_27.
66 # branch names: https://git.wikimedia.org/branches/mediawiki%2Fcore.git
67 export mw_branch=REL1_27
69 # customize these questions to something your contributors would know,
70 # and at least doesn't have the answer directly in the question
72 if ! grep -Fx '$localSettingsQuestyQuestions = array (' $mwc; then
74 $localSettingsQuestyQuestions = array (
75 "What is the name of the wiki software this site (and wikipedia) uses?" => "Mediawiki",
76 "What does f in ofswiki.org stand for?" => "Free"
82 # As set by gui installer when choosing cc by sa.
83 export mw_RightsUrl='https://creativecommons.org/licenses/by-sa/4.0/'
84 export mw_RightsText='Creative Commons Attribution-ShareAlike'
85 export mw_RightsIcon='$wgScriptPath/resources/assets/licenses/cc-by-sa.png'
88 export mwdomain=REPLACE_ME # domain name. for this site, it's ofswiki.org
89 # Alphanumeric site name for pywikibot.
90 # Here we use the domain minus the dots, which should work fine without changing.
91 export mwfamily=${mwdomain//./}
92 # install path for mediawiki. This should work fine.
93 export mw=/var/www/$mwdomain/html/w
96 # wiki sender address / wiki & wiki server contact email.
97 # see email section for more info on email
98 export mw_email="admin@$mwdomain"
101 mwc="$mw/LocalSettings.php"
104 == Download this page and run it ==
106 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.
108 ''' Requires manual step: inspect output file: /tmp/mw-setup, then run it'''
109 <source lang="bash" type="example">
110 start=' *<source lang="bash"> *'
112 ruby <<'EOF' | sed -rn "/^$start$/,/^$end$/{s/^$start|$end$/# \0/;p} > /tmp/mw-setup"
114 puts JSON.parse(`curl 'https://ofswiki.org/w/api.php?\
115 action=query&titles=Mediawiki_Setup_Guide&prop=revisions&rvprop=content&\
116 format=json'`.chomp)['query']['pages'].values[0]['revisions'][0]['*']
118 chmod +x /tmp/mw-setup
121 == Required Bash Functions ==
123 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.
126 # identify if this is a debian based distro
127 isdeb() { command -v apt &>/dev/null; }
128 # tee unique. append each stdin line if it does not exist in the file
132 for line in "${MAPFILE[@]}"; do
133 grep -xFq "$line" "$1" &>/dev/null || tee -a "$1" <<<"$line"
137 # get and reset an extension/skin repository, and enable it
140 local original_pwd="$PWD"
142 local re='[^/]*/[^/]*$'
143 [[ $url =~ $re ]] ||:
144 target=$mw/${BASH_REMATCH[0]}
145 if [[ ! -e $target/.git ]]; then
146 git clone $url $target
148 if ! cd $target; then
149 echo "mw-ext error: failed cd $target";
153 git checkout -qf origin/$mw_branch || git checkout -qf origin/master
161 mw-clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/$ext
162 if [[ -e $mw/ext/$ext/extension.json ]]; then
163 # new style extension. remove old style declaration
164 sed -i --follow-symlinks '#^require_once( "\\\$IP/extensions/\$ext/\$ext\.php" );#d' $mwc
166 wfLoadExtension( '$ext' );
170 require_once( "\$IP/extensions/$ext/$ext.php" );
174 # --quick is quicker than default flags,
175 # but still add a sleep to make sure everything works right
176 sudo -u $apache_user php $mw/maintenance/update.php -q --quick; sleep 1
180 mw-clone https://gerrit.wikimedia.org/r/p/mediawiki/skins/$skin
181 sed -i --follow-symlinks '/^wfLoadSkin/d' $mwc
182 sed -i --follow-symlinks '/^\$wgDefaultSkin/d' $mwc
184 \$wgDefaultSkin = "${skin,,*}";
185 wfLoadSkin( '$skin' );
187 sudo -u $apache_user php $mw/maintenance/update.php -q --quick; sleep 1
190 if command -v apt &>/dev/null; then
198 == Install Mediawiki Dependencies ==
200 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.
202 [[mediawikiwiki:Main Page|Mediawiki Main Page]]: the beginning of the official docs.
204 [[mediawikiwiki:Manual:Installation_requirements|Manual:Installation_requirements]]: Overview of installation requirements.
206 Note, this guide needs a little adjustment before it will work with php7.0: make sure settings are still valid, update ini path.
211 # From here on out, exit if a command fails.
212 # This will prevent us from not noticing an important failure.
213 # We recommend setting this for the entire installation session.
214 # If you are running commands interactively, it might be best to
215 # put it in your ~/.bashrc temporarily.
217 trap 'echo "$0:$LINENO:error: \"$BASH_COMMAND\" returned $?" >&2' ERR
222 # https://www.mediawiki.org/wiki/Manual:Running_MediaWiki_on_Ubuntu
224 apt-get install -y imagemagick php-mbstring
225 if apt-get install -s mediawiki &>/dev/null; then
226 # in debian wheezy time-frame distros, mediawiki was packaged.
227 apt-get -y install php-apc mediawiki
229 # https://www.mediawiki.org/wiki/Manual:Installation_requirements
230 if apt-get install -s php7.0 &>/dev/null; then
231 # note, 7.0 is untested by the editor here, since it's not
232 # available in debian 8. it's listed as supported
233 # in the mediawiki page.
234 # noninteractive to avoid mysql password prompt
235 DEBIAN_FRONTEND=noninteractive apt-get install -y apache2 mysql-server \
236 php7.0 php7.0-mysql libapache2-mod-php7.0 php7.0-xml \
239 DEBIAN_FRONTEND=noninteractive apt-get install -y apache2 mysql-server \
240 php5 php5-mysql libapache2-mod-php5 php5-apcu
243 service apache2 restart
246 # fedora deps are missing a database, so some is translated from debian packages
247 yum -y install mediawiki ImageMagick php-mysqlnd php-pecl-apcu mariadb-server
249 systemctl restart mariadb.service
250 systemctl enable mariadb.service
251 systemctl enable httpd.service
252 systemctl restart httpd.service
256 # slightly different depending on if we already set the root pass
257 if echo exit|mysql -u root -p"$dbpass"; then
258 # answer interactive prompts:
259 # mysql root pass, change pass? no, remove anon users? (default, yes)
260 # disallow remote root (default, yes), reload? (default, yes)
261 echo -e "$dbpass\nn\n\n\n\n" | mysql_secure_installation
263 # I had 1 less newline at the start when doing ubuntu 14.04,
264 # compared to debian 8, so can't say this is especially portable.
265 # It won't hurt if it fails.
266 echo -e "\n\n$dbpass\n$dbpass\n\n\n\n\n" | mysql_secure_installation
271 '''Skippable notes'''
274 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.
277 Additional packages rational
278 * ImageMagick is [https://www.mediawiki.org/wiki/Manual:Image_administration#Image_thumbnailing recommended].
279 * Gui install and [[mediawikiwiki:Manual:Cache]] recomend the apc package.
280 * 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.
282 == Install Mediawiki ==
285 Here, we [[mediawikiwiki:Download_from_Git]], or reset our installation if it is already there, and create the wiki database. [[mediawikiwiki:Manual:Installing_MediaWiki]]
290 # this will just fail if it already exists which is fine
291 if [[ ! -e .git ]]; then
292 git clone https://gerrit.wikimedia.org/r/p/mediawiki/core.git .
294 # to see available branches: https://www.mediawiki.org/wiki/Version_lifecycle
297 git checkout -f origin/$mw_branch
299 # Get the php libraries wmf uses. Based on:
300 # https://www.mediawiki.org/wiki/Download_from_Git#Fetch_external_libraries
301 if [[ ! -e vendor/.git ]]; then
302 git clone https://gerrit.wikimedia.org/r/p/mediawiki/vendor.git
305 git checkout -f origin/$mw_branch
308 # Drop any previous database which may have been installed while testing.
309 # If upgrading, we should have a db backup which will get restored.
310 # https://www.mediawiki.org/wiki/Manual:Upgrading
311 mysql -u root -p$dbpass <<'EOF' ||:
312 drop database my_wiki;
315 php $mw/maintenance/install.php --pass $wikipass --scriptpath /w \
316 --dbuser root --dbpass $dbpass "$mwdescription" "$wikiuser"
318 # lock down the wiki to only the initial owner until anti-spam measures are put in place
319 # limit edits to registered users
320 $wgGroupPermissions['*']['edit'] = false;
321 # don't allow any account creation
322 $wgGroupPermissions['*']['createaccount'] = false;
327 Note: When testing, you may need to clear the apc cache to see changes take effect in the browser. Simplest solution is
328 just restart apache. http://stackoverflow.com/questions/911158/how-to-clear-apc-cache-entries
330 ''' Skippable Notes'''
332 If we wanted to reset our installation, but leave the extension repositories alone, alter the command above to be <code>git clean -fxd</code>
334 '''Rational for choosing git sources'''
336 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.
338 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.
340 == Configure Apache ==
342 Note, non-debian based installs: modify instructions below to use /etc/httpd/conf.d/$mwdomain.conf, and don't run a2ensite.
344 I use scripts I maintains separately to setup Let's Encrypt certificates and apache config: (url pending).
346 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.
348 '''Not for production:'''
349 <source lang="bash" type="example">
350 teeu /etc/hosts<<<"127.0.0.1 $mwdomain"
353 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:
355 '''Optional & requires additional steps:'''
356 <source lang="bash" type="example">
357 git clone https://github.com/certbot/certbot
359 ./certbot-auto apache
360 cd /etc/apache/sites-available
361 mv 000-default-le-ssl.conf $mwdomain.conf
362 rm ../sites-enabled/000-default-le-ssl.conf
363 # edit $mwdomain.conf, so documentroot is /var/www/$mwdomain/html
364 # and ServerName is $mwdomain
365 a2ensite $mwdomain.conf
367 Then, copy the input to apache-site below and insert it into the apache config.
369 Here, we use some scripts automate setting up the Let 's Encrypt cert and
375 git_site=https://iankelling.org/git
376 git clone $git_site/acme-tiny-wrapper
380 acme-tiny-wrapper/acme-tiny-wrapper $mwdomain
382 git clone $git_site/basic-https-conf
384 ServerAdmin $mw_email
386 # make the site's root url go to our main page
387 RewriteRule ^/?wiki(/.*)?\$ %{DOCUMENT_ROOT}/w/index.php [L]
388 # use short urls https://www.mediawiki.org/wiki/Manual:Short_URL
389 RewriteRule ^/*\$ %{DOCUMENT_ROOT}/w/index.php [L]
391 find -L $(readlink -f $mw) -name .htaccess \
392 | while read line; do
393 echo -e "<Directory ${line%/.htaccess}>\n $(< $line)\n</Directory>";
395 } | basic-https-conf/apache-site -r ${mw%/*} - $mwdomain
400 Now mediawiki should load in your browser at $mwdomain .
402 Allow proper search bots and internet archiver bots, via [[Mediawiki:Robots.txt]],
403 and install the default skin.
406 dd of=$mw/../robots.txt <<'EOF'
409 User-agent: ia_archiver
415 '''Skippable Notes'''
417 This section assumes we are redirecting www to a url without www.
419 [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.
421 == Mediawiki Settings ==
423 Overall reference: [[mediawikiwiki:Manual:Configuration_settings]].
425 Settings which the gui setup prompts for but aren't set by the automated install script.
428 \$wgServer = "https://$mwdomain";
429 \$wgDBserver = "localhost";
430 \$wgRightsUrl = "$mw_RightsUrl";
431 \$wgRightsText = "$mw_RightsText";
432 \$wgRightsIcon = "$mw_RightsIcon";
435 Settings I recommend which are different than the defaults.
438 \$wgPasswordSender = "$mw_email";
439 \$wgEmergencyContact = "$mw_email";
440 \$wgEnotifUserTalk = true; # UPO
441 \$wgEnotifWatchlist = true; # UPO
442 \$wgMainCacheType = CACHE_ACCEL;
443 \$wgEnableUploads = true;
444 \$wgUseInstantCommons = true;
451 # from https://www.mediawiki.org/wiki/Manual:Short_URL
452 $wgArticlePath = "/wiki/$1";
454 # https://www.mediawiki.org/wiki/Manual:Combating_spam
455 # check that url if our precautions don't work
456 # not using nofollow is good practice, as long as we avoid spam.
457 $wgNoFollowLinks = false;
458 # Allow user customization.
459 $wgAllowUserJs = true;
460 $wgAllowUserCss = true;
462 # use imagemagick over GD
463 $wgUseImageMagick = true;
467 # https://www.mediawiki.org/wiki/Manual:Configuring_file_uploads
468 # Increase from default of 2M to 100M.
469 # This will at least allow high res pics etc.
470 php_ini=$(php -r 'echo(php_ini_loaded_file());')
471 sed -i --follow-symlinks 's/^\(upload_max_filesize\|post_max_size\)\b.*/\1 = 100M/' $php_ini
473 service apache2 restart
475 systemctl restart httpd.service
478 # if you were to install as a normal user, you would need this for images
479 # sudo usermod -aG $apache_user $USER
481 # this doesn't propogate right away
482 chgrp -R $apache_user $mw/images
483 chmod -R g+w $mw/images
486 Style settings. Omit to use a different style.
490 #$wgFooterIcons = null;
492 # Make the toolbox go into the drop down.
494 if ! git remote show ian-kelling &>/dev/null; then
495 git remote add ian-kelling https://iankelling.org/git/Vector
497 git fetch ian-kelling
498 git checkout ian-kelling/REL1_27-toolbox-in-dropdown
501 == Install and Configure Mediawiki Extensions ==
503 When installing extensions on a wiki with important content, backup first as a precaution.
505 ''' Extensions with no configuration needed '''
511 | [[mediawikiwiki:Extension:Cite|Extension:Cite]]
512 | Have references in footnotes.
514 | [[mediawikiwiki:Extension:CiteThisPage|Extension:CiteThisPage]]
515 | Ability to generate citations to pages in a variety of styles.
517 | [[mediawikiwiki:Extension:CSS|Extension:CSS]]
518 | Allows CSS stylesheets to be included in specific articles
520 | [[mediawikiwiki:Extension:Echo|Extension:Echo]]
521 | Notification subsystem for usage by other extensions
523 | [[mediawikiwiki:Extension:Gadgets|Extension:Gadgets]]
524 | UI extension system for users
526 | [[mediawikiwiki:Extension:ImageMap|Extension:ImageMap]]
527 | Links for a region of an image
529 | [[mediawikiwiki:Extension:Interwiki|Extension:Interwiki]]
530 | Tool for nice links to other wikis
532 | [[mediawikiwiki:Extension:News|Extension:News]]
533 | Embed or rss recent changes
535 | [[mediawikiwiki:Extension:Nuke|Extension:Nuke]]
536 | Mass delete of pages, in the case of spam
538 | [[mediawikiwiki:Extension:ParserFunctions|Extension:ParserFunctions]]
539 | Useful for templates
541 | [[mediawikiwiki:Extension:Poem|Extension:Poem]]
542 | Useful for formatting things various ways
544 | [[mediawikiwiki:Extension:SyntaxHighlight_GeSHi|Extension:SyntaxHighlight_GeSHi]]
545 | Source code highlighting
547 | [[mediawikiwiki:Extension:Variables|Extension:Variables]]
548 | Define per-page variables
552 mw-ext Cite CiteThisPage CSS Echo Gadgets ImageMap Interwiki News \
553 Nuke ParserFunctions Poem SyntaxHighlight_GeSHi Variables
557 ''' [[mediawikiwiki:Extension:AntiSpoof|Extension:AntiSpoof]]: Disallow usernames with unicode trickery to look like existing names'''
561 # recommended setup script to account for existing users
562 sudo -u $apache_user php $mw/extensions/AntiSpoof/maintenance/batchAntiSpoof.php
566 ''' [[mediawikiwiki:CheckUser|Extension:CheckUser]]: Get ip addresses from inside mediawiki so you can ban users'''
568 Requires special install steps or we can get into a bad state. Add a sleep like the default of update.php to avoid errors.
571 sudo -u $apache_user php $mw/extensions/CheckUser/install.php; sleep 1
575 '''[[mediawikiwiki:Extension:Wikidiff2|Extension:Wikidiff2]]: Faster and international character supported page diffs'''
577 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.
580 apt-get -y install php-wikidiff2
582 $wgExternalDiffEngine = 'wikidiff2';
584 dir=$(dirname $(php -r 'echo(php_ini_loaded_file());'))/../apache2/conf.d
585 ln -sf ../../mods-available/wikidiff2.ini $dir
586 service apache2 restart
591 ''' [[mediawikiwiki:Extension:Math|Extension:Math]] Display equations'''
595 # php5-curl according to Math readme
598 if ! apt-get -s install $curl_pkg &>/dev/null; then
601 apt-get -y install latex-cjk-all texlive-latex-extra texlive-latex-base \
602 ghostscript imagemagick ocaml $curl_pkg make
604 # todo, php5-curl equivalent on fedora
605 yum -y install texlive-cjk ghostscript ImageMagick texlive ocaml
607 service apache2 restart
609 cd $mw/extensions/Math/math; make # makes texvc
610 cd $mw/extensions/Math/texvccheck; make
613 # Enable MathJax as rendering option
614 $wgUseMathJax = true;
615 # Enable LaTeXML as rendering option
616 $wgMathValidModes[] = 'latexml';
617 # Set LaTeXML as default rendering option, because it is nicest
618 $wgDefaultUserOptions['math'] = 'latexml';
622 '''Skippable notes'''
624 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.
627 ''' [[mediawikiwiki:Extension:SpamBlacklist|Extension:SpamBlacklist]]: Import/create IP blacklists, mainly for spam'''
631 if ! grep -F '$wgSpamBlacklistFiles = array(' $mwc &>/dev/null; then
633 $wgEnableDnsBlacklist = true;
634 $wgDnsBlacklistUrls = array( 'xbl.spamhaus.org', 'dnsbl.tornevall.org' );
636 ini_set( 'pcre.backtrack_limit', '10M' );
637 $wgSpamBlacklistFiles = array(
638 "[[m:Spam blacklist]]",
639 "http://en.wikipedia.org/wiki/MediaWiki:Spam-blacklist"
645 ''' [[mediawikiwiki:Extension:TitleBlacklist|Extension:TitleBlacklist]]: Anti-spam '''
648 mw-ext TitleBlacklist
649 if ! grep -F '$wgTitleBlacklistSources = array(' $mwc &>/dev/null; then
651 $wgTitleBlacklistSources = array(
654 'src' => 'MediaWiki:Titleblacklist',
658 'src' => 'http://meta.wikimedia.org/w/index.php?title=Title_blacklist&action=raw',
665 ''' [[mediawikiwiki:Extension:WikiEditor|Extension:WikiEditor]]: Editing box extras and a fast preview tab '''
670 # Enable Wikieditor by default
671 $wgDefaultUserOptions['usebetatoolbar'] = 1;
672 $wgDefaultUserOptions['usebetatoolbar-cgd'] = 1;
674 # Display the Preview and Changes tabs
675 $wgDefaultUserOptions['wikieditor-preview'] = 1;
679 ''' [[mediawikiwiki:CategoryTree|Extension:CategoryTree]]: Enables making nice outlines of pages in a category'''
683 # Mediawiki setting dependency for CategoryTree
688 ''' [[mediawikiwiki:Extension:AbuseFilter|Extension:AbuseFilter]]: Complex abilities to stop abuse '''
690 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:
694 $wgGroupPermissions['sysop']['abusefilter-modify'] = true;
695 $wgGroupPermissions['*']['abusefilter-log-detail'] = true;
696 $wgGroupPermissions['*']['abusefilter-view'] = true;
697 $wgGroupPermissions['*']['abusefilter-log'] = true;
698 $wgGroupPermissions['sysop']['abusefilter-private'] = true;
699 $wgGroupPermissions['sysop']['abusefilter-modify-restricted'] = true;
700 $wgGroupPermissions['sysop']['abusefilter-revert'] = true;
704 '''[[mediawikiwiki:Extension:ConfirmEdit|Extension:ConfirmEdit]]: Custom Captcha'''
706 Uses captchaArray defined in mw_vars.
712 wfLoadExtension( 'ConfirmEdit/QuestyCaptcha' );
713 $wgCaptchaClass = 'QuestyCaptcha';
714 # only captcha on registration
715 $wgGroupPermissions['user' ]['skipcaptcha'] = true;
716 $wgGroupPermissions['autoconfirmed']['skipcaptcha'] = true;
718 if ! grep -Fx 'foreach ( $localSettingsQuestyQuestions as $key => $value ) {' $mwc; then
720 foreach ( $localSettingsQuestyQuestions as $key => $value ) {
721 $wgCaptchaQuestions[] = array( 'question' => $key, 'answer' => $value );
727 Enable account creation that we initially disabled.
729 sed -i --follow-symlinks "/\\\$wgGroupPermissions\\['\\*'\\]\\['createaccount'\\] = false;/d" $mwc
732 == Additional Configuration with Pywikibot ==
734 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.
737 '''Pywikibot Install'''
739 [[mediawikiwiki:Manual:Pywikibot/Installation|Manual:Pywikibot/Installation]]
743 if [[ ! -e ~/pywikibot/.git ]]; then
744 git clone --recursive \
745 https://gerrit.wikimedia.org/r/pywikibot/core.git ~/pywikibot
754 '''Pywikibot Configuration'''
756 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]]
761 dd of=user-config.py <<EOF
763 usernames["$mwfamily"]['en'] = u'$wikiuser'
765 console_encoding = 'utf-8'
766 password_file = "secretsfile"
769 dd of=secretsfile <<EOF
770 ("$wikiuser", "$wikipass")
773 # it won't overrwrite an existing file. Remove if if one exists
774 rm -f pywikibot/families/${mwfamily}_family.py
776 apt-get install -y python-requests
778 yum -y install python-requests
781 python generate_family_file.py https://$mwdomain/wiki/Main_Page "$mwfamily"
783 # Note, this needed only for ssl site
784 tee -a pywikibot/families/${mwfamily}_family.py<<'EOF'
785 def protocol(self, code):
791 '''Pywikibot Script'''
793 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]].
798 dd of=scripts/${mwfamily}_setup.py<<EOF
802 site = pywikibot.Site()
804 page = pywikibot.Page(site, p)
806 #force is for some anti-bot thing, not necessary in my testing, but might as well include it
807 page.save(force=True)
809 # Small/medium noncommercial wiki should be fine with no privacy policy
810 # based on https://www.mediawiki.org/wiki/Manual:Footer
811 x("MediaWiki:Privacy")
813 # licenses for uploads. Modified from the mediawiki's wiki
814 x("MediaWiki:Licenses", u"""* Same as this wiki's text (preferred)
815 ** CC BY-SA or GFDL| Creative Commons Attribution ShareAlike or GNU Free Documentation License
817 ** Unknown_copyright|I don't know exactly
818 ** PD|PD: public domain
819 ** CC BY|Creative Commons Attribution
820 ** CC BY-SA|Creative Commons Attribution ShareAlike
821 ** GFDL|GFDL: GNU Free Documentation License
822 ** GPL|GPL: GNU General Public License
823 ** LGPL|LGPL: GNU Lesser General Public License""")
824 x("MediaWiki:Copyright", '$mw_license')
825 x("MediaWiki:Mainpage-description", "$mwdescription")
829 # The rest of the settings are for the site style
831 # Remove various clutter
832 x("MediaWiki:Lastmodifiedat")
833 x("MediaWiki:Disclaimers")
834 x("MediaWiki:Viewcount")
835 x("MediaWiki:Aboutsite")
836 # remove these lines from sidebar
837 # ** recentchanges-url|recentchanges
838 # ** randompage-url|randompage
840 x("MediaWiki:Sidebar", """* navigation
841 ** mainpage|mainpage-description
847 # helpfull doc: https://www.mediawiki.org/wiki/Manual:Interface/Sidebar
848 x("mediawiki:Common.css", """/* adjust sidebar to just be home link and up top */
849 /* panel width increased to fit full wiki name. */
850 div#mw-panel { top: 10px; padding-top: 0em; width: 20em }
851 div#footer, #mw-head-base, div#content { margin-left: 1em; }
852 #left-navigation { margin-left: 1em; }
855 /* logo, and toolbar hidden */
856 #p-logo, #p-tb.portal {
860 /* make the font size smaller for the misc stuff */
868 div#mw-content-text {
874 python pwb.py ${mwfamily}_setup
878 ''' Skippable Notes '''
880 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.
882 Family name, and all its duplicattions documented as supposed to be $wgSitename, but it works fine using any name.
884 == Automatic Backups ==
886 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.
888 <source lang="bash" type="backup">
889 backup_script=/etc/cron.daily/mediawiki_backup
890 sudo dd of=$backup_script <<'EOFOUTER'
892 # if we get an error, keep going but return it at the end
894 trap 'last_error=$?' ERR
896 # No strict because the host is likely not named the same as
898 ssh="ssh -oStrictHostKeyChecking=no"
899 logfile=/var/log/${mwdomain}_backup.log
901 echo "#### starting backup at $(date) ####"
902 $ssh root@$mwdomain <<ENDSSH
905 \$wgReadOnly = 'Dumping Database, Access will be restored shortly';
907 mkdir -p ~/wiki_backups
908 mysqldump -p$dbpass --default-character-set=binary my_wiki > ~/wiki_backups/wiki_db_backup
909 sed -i '\$ d' $mwc # delete read only setting
911 # add no strict option to the defaults
913 rdiff() { rdiff-backup --remote-schema "$ssh -C %s rdiff-backup --server" "$@"; }
915 rdiff root@$mwdomain::/root/wiki_backups ~/backup/${mwdomain}_wiki_db_backup
916 rdiff root@$mwdomain::$mw ~/backup/${mwdomain}_wiki_file_backup
918 echo "=== ending backup at $(date) ===="
920 if [[ $last_error != 0 ]]; then
921 echo "backup for $mwdomain failed. See $logfile"
926 sudo chmod +x $backup_script
929 If you are like most people and don't use the old-school mail spool, setup the backup system to send mail externally. Some ways to do that are on this [http://unix.stackexchange.com/questions/36982/can-i-set-up-system-mail-to-use-an-external-smtp-server stackoverflow answer]. Then make local mail to your user get forwarded to an address you will read:
931 '''Optional & requires additional steps'''
932 <source lang="bash" type="example">
933 sed -i --follow-symlinks "/^root:/d" /etc/aliases
934 echo "root: EXAMPLE_ONLY_REPLACE_ME@gmail.com" >> /etc/aliases
938 == Restoring Backups ==
940 '''Whenever you implement a backup system, you should test that restoring the backup works.'''
942 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. However, we backup the entire Mediawiki directory in case you forget to record a step, or some misbehaving code stores some state in a file. Since most people don't record the steps they took to setup Mediawiki, this is also the officially recommended method. Here we restore only the database and images folder, which should help identify any of those aforementioned issues. See [[mediawikiwiki:Manual:Restoring a wiki from backup]] if you run into any problems.
944 To test a backup restore:
945 # Do a backup of your wiki with some content in it, as described in the previous section
946 # Move your mediawiki install directory, or setup Mediawiki on a new machine
947 # Re-execute the mediawiki install steps
948 # Change REPLACE_ME in the code below (as in the backup section so you get the right variables),
949 # Execute the code on the backup machine.
952 <source lang="bash" type="example">
955 HOSTNAME=REPLACE_ME source ~/mw_vars
956 rdiff-backup -r now ~/backup/${mwdomain}_wiki_file_backup /tmp/wiki_file_restore
957 scp -r /tmp/wiki_file_restore/images root@$mwdomain:$mw/images
958 rdiff-backup -r now ~/backup/${mwdomain}_wiki_db_backup /tmp/wiki_db_restore
959 scp -r /tmp/wiki_db_restore root@$mwdomain:/tmp
960 ssh root@$mwdomain <<EOF
961 mysql -u root -p$dbpass my_wiki < /tmp/wiki_db_restore/wiki_db_dump
962 php $mw/maintenance/update.php
967 Then browse to your wiki and see if everything appears to work.
971 Subscribe to get release and security announcements [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki-announce].
973 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).
975 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]]
977 Minor updates script:
979 s=/etc/cron.daily/mediawiki_update
985 git checkout origin/$mw_branch
986 git rebase ian/REL1_23-toolbox-in-dropdown
992 git checkout origin/$mw_branch || git checkout -qf origin/master
996 php $mw/maintenance/update.php -q
1001 == Upgrading Major Versions ==
1003 Reference documentation is at [[mediawikiwiki:Manual:Upgrading]]
1007 # Read the "Upgrade notices for MediaWiki administrators" on the upgrade version and any skipped versions at [[mediawikiwiki:Version_lifecycle]].
1008 # Setup a blank test wiki with the new version.
1009 # Backup the old database, restore it to the new wiki, run php maintenance/update.php.
1010 # If everything looks good, repeat and replace the old wiki with the new one.
1014 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:
1016 * Find new spam quickly, revert it & ban the user.
1017 ** 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."
1018 ** 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].
1019 * Require registration to edit, and a custom captcha question on registration.
1020 * Install all non-user inhibiting anti-spam extensions / settings that take a reasonable amount of time to figure out.
1022 == Choosing Extensions ==
1024 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.
1026 Here are brief descriptions of extensions that are part of distributions and why they were rejected for this wiki.
1028 {| class="wikitable"
1030 | '''InputBox''' || Add html forms to pages. Can't imagine using it. Would install if I did.
1032 | '''Pdfhandler''' || Gallery of pages from a pdf file. Can't imagine using it. Would install if I did.
1034 | '''Footnote''' || deprecated in newer versions
1036 | '''NewUserNotif''' || Send me a notification when a user registers. Seems like an excessive notification.
1038 | '''NewestPages''' || A page creation history that doesn't expire like recent-changes. Meh
1040 | '''RSSReader''' || Embed an rss feed. Can't imagine using it. Would install if I did.
1042 | '''Openid''' || Poor UI. 2 pages & 2 links <login> <login with openid> which is confusing & ugly.
1044 | '''Validator''' || dependency of of semantic
1046 | '''Semantic''' || Seems like a lot of trouble around analyzing kinds of data which my wiki will not have.
1048 | '''wikicalendar''' || Make a calendar of events etc. Can't imagine using it. Would install if I did.
1053 ''' Web Analytics Software '''
1055 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.
1057 ''' Mediawiki Documentation Quality '''
1059 Overall the documentation is good, but like wikipedia, it depends.
1061 The closer a topic is to core functionality and commonly used features, the better the documentation is likely to be. My guess is that 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 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.
1063 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].
1066 '''Bash here documents, EOF vs 'EOF' '''
1068 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.
1071 ''' Mediawiki automation tools survey 7/2014 '''
1074 * https://github.com/ianweller/mw
1075 * http://search.cpan.org/~markj/WWW-Mediawiki-Client/bin/mvs
1076 * https://github.com/alexz-enwp/wikitools 3000 lines of code, no response to a bug reports in 2/2014
1078 Getting basic maintenance
1079 * https://github.com/mwclient/mwclient 2000 lines of code
1081 Actively developed, used by wikimedia foundation a lot.
1082 * [[mediawikiwiki:Manual:Pywikibot]]
1085 ''' Troubleshooting Errors '''
1087 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]]
1091 This page and this wiki is licensed under cc-by-sa 4.0.
1092 This means the code is compatible with gplv3.
1094 == todo list for this page ==
1096 * Check if there are any new default extensions 1.27 which I haven't evaluated.
1097 * Test for any new config values set by the 1.27 gui install method.
1098 * Get Visual editor extension.
1099 * Don't require registration for edits