3 '''Currently undergoing revisions to upgrade from mediawiki version 1.23 to 1.27.
4 Should be done on 5/30/2016'''
6 '''tldr''': Automated setup on gnu/linux after you set options in [[#Dependent Variables and Functions]], except email. Any code which is not ready to be run has bold text saying so immediately before it.
8 ''' Goals / Why use this guide? '''
10 * Good recommendations. Official docs mostly avoid recommendations among a myriad of possibilities
11 * Closely references & supplements official documentation
12 * Explicit automation support wherever practical
13 * Used to setup this site (style optional)
14 * Contributions welcome. This site will be updated/tested with changes to this document!
15 * Support for multiple linux distros
16 * Holistic scope (backups, server setup), but sections stand on their own
17 * Explicit support for production & local testing instance. Additions for production like https and web analytics.
18 * Edits to this page are closely monitored by the original author.
22 * Self hosting, single Linux system with Bash shell
23 * Root shell is assumed throughout
24 * Code blocks are [https://en.wikipedia.org/wiki/Idempotent idempotent] unless stated otherwise
28 Very minor adjustments needed for other distros. Help expand this list.
31 * Ubuntu 14.04 (tested)
34 == Production Server Prerequisites ==
36 '''Getting a Server & a Domain'''
38 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.
42 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.
44 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]]
48 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:
50 * Find new spam quickly, revert it & ban the user.
51 ** 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."
52 ** 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].
53 * Require registration to edit, and a custom captcha question on registration.
54 * Install all non-user inhibiting anti-spam extensions / settings that take a reasonable amount of time to figure out.
56 == Download all ready to use source code blocks into a single script ==
58 Source block that are not ready to use have a bold warning just before them (and a tag on the block) and are skipped.
59 ''' Requires customization: outputs to stdout'''
60 <source lang="bash" type="example">
61 start=' *<source lang="bash"> *'
63 ruby <<'EOF' | sed -rn "/^$start$/,/^$end$/{s/^$start|$end$/# \0/;p}"
65 puts JSON.parse(`curl 'https://ofswiki.org/w/api.php?\
66 action=query&titles=Mediawiki_Setup_Guide&prop=revisions&rvprop=content&\
67 format=json'`.chomp)['query']['pages'].values[0]['revisions'][0]['*']
71 == Dependent Variables and Functions ==
74 # Save the code in this section to a file (~/mw_vars is suggested)
75 # Source it at the beginning of scripts containing later commands
76 # Source it from your .bashrc file while you are setting up Mediawiki
78 '''Requires customization:'''
79 <source lang="bash" type="example">
80 # Replease REPLACE_ME as appropriate
82 export mwdescription="Opinionated Free Software Wiki"
84 # username/pass of the first wiki admin user
85 export wikiuser="Ian Kelling"
86 export wikipass=REPLACE_ME
88 # root password for the mysql database
89 export dbpass=REPLACE_ME
91 # password for piwik web analytics admin
92 export piwik_pass=REPLACE_ME
94 # git branch for mediawiki + extensions
95 # branch names: https://git.wikimedia.org/branches/mediawiki%2Fcore.git
96 export mw_branch=REL1_27
98 # customize these questions to something your contributors would know,
99 # is not super common / scriptable, and doesn't have the answer in the question
101 if ! grep -Fx '$localSettingsQuestyQuestions = array (' $mwc
103 $localSettingsQuestyQuestions = array (
104 "What is the name of the wiki software this site (and wikipedia) uses?" => "Mediawiki",
105 "What does f in ofswiki.org stand for?" => "Free"
110 # As set by gui installer when choosing cc by sa.
111 export mw_RightsUrl="https://creativecommons.org/licenses/by-sa/4.0/";
112 export mw_RightsText="Creative Commons Attribution-ShareAlike";
113 export mw_RightsIcon="$wgResourceBasePath/resources/assets/licenses/cc-by-sa.png";
116 # domain name and install paths. These are examples, change as needed.
117 export mwfamily=ofswiki # short alphanumeric name for pywikibot
118 export mwdomain=ofswiki.org
119 export mw=/var/www/$mwdomain/html/w
122 # wiki sender address / wiki & wiki server contact email.
123 # see email section for more info on email
124 export mw_email="admin@$mwdomain"
127 Here we define some small useful bash functions. This should be part of the same file.
130 # for convenience, Mediawiki config file
131 mwc="$mw/LocalSettings.php"
139 # get and reset an extension/skin repository, and enable it
140 mw-ext () { mw-extra extension $@; }
141 mw-skin() { mw-extra skin $@; }
144 local type=${1}s # extension or skin
147 if [[ $1 == -g ]]; then
154 local original_pwd="$PWD"
155 # it's ok that this fails if we already have it
156 url=https://git.wikimedia.org/git/mediawiki
157 target=$mw/$type/$ext
158 git clone $url/$type/$ext.git $target
159 if ! cd $target; then
160 echo "mw-ext error: failed cd $mw/extensions/$ext";
164 git checkout -qf origin/$mw_branch || git checkout -qf origin/master
170 if [[ -e $target/extension.json ]]; then
171 # new style extension. remove old style declaration
172 sed -i '#^require_once( "\\\$IP/extensions/\$ext/\$ext\.php" );#d' $mwc
174 wfLoadExtension( '$ext' );
178 require_once( "\$IP/extensions/$ext/$ext.php" );
183 sed -i '/^wfLoadSkin/d' $mwc
184 sed -i '/^\$wgDefaultSkin/d' $mwc
186 $wgDefaultSkin = "${ext,,*}";
187 wfLoadSkin( 'Vector' );
192 # --quick is quicker than default flags,
193 # but still add a sleep to make sure everything works right
194 sudo -u $apache_user php $mw/maintenance/update.php -q --quick; sleep 1
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.
211 # noninteractive to avoid mysql password prompt
212 DEBIAN_FRONTEND=noninteractive apt-get -y install mediawiki ImageMagick php5-mysqlnd php-apc
213 service apache2 restart
215 # fedora deps are missing a database, so some is translated from debian packages
216 yum -y install mediawiki ImageMagick php-mysqlnd php-pecl-apcu mariadb-server
218 systemctl restart mariadb.service
219 systemctl enable mariadb.service
220 systemctl enable httpd.service
221 systemctl restart httpd.service
225 # slightly different depending on if we already set the root pass
226 if echo exit|mysql -u root -p"$dbpass"; then
227 # answer interactive prompts:
228 # mysql root pass, change pass? no, remove anon users? (default, yes)
229 # disallow remote root (default, yes), reload? (default, yes)
230 echo -e "$dbpass\nn\n\n\n\n" | mysql_secure_installation
232 # I had 1 less newline at the start when doing ubuntu 14.04,
233 # compared to debian 8, so can't say this is especially portable.
234 # It won't hurt if it fails.
235 echo -e "\n\n$dbpass\n$dbpass\n\n\n\n\n" | mysql_secure_installation
240 '''Skippable notes'''
243 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.
246 Additional packages rational
247 * ImageMagick is [https://www.mediawiki.org/wiki/Manual:Image_administration#Image_thumbnailing recommended].
248 * Gui install and [[mediawikiwiki:Manual:Cache]] recomend the apc package.
249 * 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.
251 == Install Mediawiki ==
254 Here, we [[mediawikiwiki:Download_from_Git]], or reset our installation if it is already there, and create the wiki database. [[mediawikiwiki:Manual:Installing_MediaWiki]]
259 # this will just fail if it already exists which is fine
260 git clone https://gerrit.wikimedia.org/r/p/mediawiki/core.git .
261 # to see available branches: https://www.mediawiki.org/wiki/Version_lifecycle
264 git checkout -f origin/$mw_branch
266 # Get the php libraries wmf uses. Based on:
267 # https://www.mediawiki.org/wiki/Download_from_Git#Fetch_external_libraries
268 git clone https://gerrit.wikimedia.org/r/p/mediawiki/vendor.git
270 git checkout -f origin/$mw_branch
273 # Drop any previous database which may have been installed while testing.
274 # If upgrading, we should have a db backup which will get restored.
275 # https://www.mediawiki.org/wiki/Manual:Upgrading
276 mysql -u root -p$dbpass <<'EOF'
277 drop database my_wiki;
280 php $mw/maintenance/install.php --pass $wikipass --scriptpath /w \
281 --dbuser root --dbpass $dbpass "$mwdescription" "$wikiuser"
283 # lock down the wiki to only the initial owner until anti-spam measures are put in place
284 # limit edits to registered users
285 $wgGroupPermissions['*']['edit'] = false;
286 # don't allow any account creation
287 $wgGroupPermissions['*']['createaccount'] = false;
292 Note: When testing, you may need to clear the apc cache to see changes take effect in the browser. Simplest solution is
293 just restart apache. http://stackoverflow.com/questions/911158/how-to-clear-apc-cache-entries
295 ''' Skippable Notes'''
297 If we wanted to reset our installation, but leave the extension repositories alone, alter the command above to be <code>git clean -fxd</code>
299 '''Rational for choosing git sources'''
301 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.
303 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.
305 == Get Piwik Files ==
307 Because it's really fun to look at your traffic stats. This is only needed for a production site. We get these files now so that we can take them into account when configuring apache in the next section.
309 [http://piwik.org/docs/installation-maintenance/ Overall installation guide]
312 tmpdir="$(mktemp -d)"
314 wget http://builds.piwik.org/piwik.zip
315 if isdeb; then apt-get -y install unzip; else yum -y install unzip; fi
317 # gui installer suggested command
319 chown -R www-data:www-data piwik
321 chown -R apache:apache piwik
323 # remove any existing directory
324 rm -rf $mw/../analytics
325 mv piwik $mw/../analytics
330 == Configure Apache ==
332 Note, non-debian based installs: modify instructions below to use /etc/httpd/conf.d/$mwdomain.conf, and don't run a2ensite.
334 I use scripts I maintains separately to setup Let's Encrypt certificates and apache config: (url pending).
336 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.
338 '''Not for production:'''
339 <source lang="bash" type="example">
340 teeu /etc/hosts<<<"127.0.0.1 $mwdomain"
343 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:
345 '''Optional & requires additional steps:'''
346 <source lang="bash" type="example">
347 git clone https://github.com/certbot/certbot
349 ./certbot-auto apache
350 cd /etc/apache/sites-available
351 mv 000-default-le-ssl.conf $mwdomain.conf
352 rm ../sites-enabled/000-default-le-ssl.conf
353 # edit $mwdomain.conf, so documentroot is /var/www/$mwdomain/html
354 # and ServerName is $mwdomain
355 a2ensite $mwdomain.conf
357 Then, copy the input to apache-site below and insert it into the apache config.
359 Here, I use my scripts to setup apache. It's behind nginx because the same server hosts other sites which are not convenient to use the same apache instance.
364 acme-tiny-wrapper $mwdomain
365 dd of=/etc/apache2/ports.conf <<'EOF'
369 ServerAdmin $mw_email
371 # make the site's root url go to our main page
372 RewriteRule ^/?wiki(/.*)?\$ %{DOCUMENT_ROOT}/w/index.php [L]
373 # use short urls https://www.mediawiki.org/wiki/Manual:Short_URL
374 RewriteRule ^/*\$ %{DOCUMENT_ROOT}/w/index.php [L]
376 find -L $(readlink -f $mw/..) -name .htaccess \
377 | while read line; do
378 echo -e "<Directory ${line%/.htaccess}>\n $(< $line)\n</Directory>";
380 } | apache-site -i -p 127.0.0.1:8082 -- - $mwdomain
381 nginx-site -p 8082 $mwdomain
385 Turn on the new configuration
388 a2ensite $mwdomain.conf
391 # We restart rather than reload because of the module
392 service apache2 restart
394 systemctl reload httpd.service
398 Now mediawiki should load in your browser at $mwdomain .
400 Allow proper search bots and internet archiver bots, via [[Mediawiki:Robots.txt]]
403 dd of=$mw/../robots.txt <<'EOF'
406 User-agent: ia_archiver
411 '''Skippable Notes'''
413 This section assumes we are redirecting www to a url without www.
415 [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 piwik 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.
417 == Mediawiki Settings ==
419 Overall reference: [[mediawikiwiki:Manual:Configuration_settings]].
421 Settings which the gui setup prompts for but aren't set by the automated install script.
424 \$wgServer = "https://$mwdomain";
425 \$wgDBserver = "localhost";
426 \$wgRightsUrl = "$mw_RightsUrl";
427 \$wgRightsText = "$mw_RightsText";
428 \$wgRightsIcon = "$mw_RightsIcon";
429 wfLoadSkin( 'Vector' );
432 Settings I recommend which are different than the defaults.
435 \$wgPasswordSender = "$mw_email";
436 \$wgEmergencyContact = "$mw_email";
437 \$wgEnotifUserTalk = true; # UPO
438 \$wgEnotifWatchlist = true; # UPO
439 \$wgMainCacheType = CACHE_ACCEL;
440 \$wgEnableUploads = true;
441 \$wgUseInstantCommons = true;
448 # from https://www.mediawiki.org/wiki/Manual:Short_URL
449 $wgArticlePath = "/wiki/$1";
451 # https://www.mediawiki.org/wiki/Manual:Combating_spam
452 # check that url if our precautions don't work
453 # not using nofollow is good practice, as long as we avoid spam.
454 $wgNoFollowLinks = false;
455 # Allow user customization.
456 $wgAllowUserJs = true;
457 $wgAllowUserCss = true;
459 # use imagemagick over GD
460 $wgUseImageMagick = true;
464 # https://www.mediawiki.org/wiki/Manual:Configuring_file_uploads
465 # Increase from default of 2M to 100M.
466 # This will at least allow high res pics etc.
467 php_ini=$(isdeb && echo /etc/php5/apache2/php.ini || echo /etc/php.ini)
468 sed -i 's/^\(upload_max_filesize\)\b.*/\1 = 100M/'
469 sed -i 's/^\(post_max_size\)\b.*/\1 = 100M/'
471 service apache2 restart
473 systemctl restart httpd.service
476 # if you were to install as a normal user, you would need this for images
477 # sudo usermod -aG $apache_user $USER
479 # this doesn't propogate right away
480 chgrp -R $apache_user $mw/images
481 chmod -R g+w $mw/images
484 Style settings. Omit to use a different style.
488 $wgShowIPinHeader = false;
489 $wgFooterIcons = null;
491 # Make the toolbox go into the drop down.
493 git remote add ian git@gitorious.org:mediawiki-toolbox-patch/mediawiki-toolbox-patch.git
495 git rebase ian/REL1_23-toolbox-in-dropdown
498 == Install and Configure Mediawiki Extensions ==
500 When installing extensions on a wiki with important content, backup first as a precaution.
502 ''' Extensions with no configuration needed '''
508 | [[mediawikiwiki:Extension:Cite|Extension:Cite]]
509 | Have references in footnotes.
511 | [[mediawikiwiki:Extension:CiteThisPage|Extension:CiteThisPage]]
512 | Ability to generate citations to pages in a variety of styles.
514 | [[mediawikiwiki:Extension:CSS|Extension:CSS]]
515 | Allows CSS stylesheets to be included in specific articles
517 | [[mediawikiwiki:Extension:DynamicPageList|Extension:DynamicPageList]]
518 | Embed page lists from categories & combinations of categories
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 DynamicPageList 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 ln -sf ../../mods-available/wikidiff2.ini /etc/php5/apache2/conf.d
585 service apache2 restart
590 ''' [[mediawikiwiki:Extension:Math|Extension:Math]] Display equations'''
594 # php5-curl according to Math readme
596 apt-get -y install latex-cjk-all texlive-latex-extra texlive-latex-base ghostscript imagemagick ocaml php5-curl
598 # todo, php5-curl equivalent on fedora
599 yum -y install texlive-cjk ghostscript ImageMagick texlive ocaml
601 ln -sf ../../mods-available/curl.ini /etc/php5/apache2/conf.d
602 service apache2 restart
604 cd $mw/extensions/Math/math; make # makes texvc
605 cd $mw/extensions/Math/texvccheck; make
608 # Enable MathJax as rendering option
609 $wgUseMathJax = true;
610 # Enable LaTeXML as rendering option
611 $wgMathValidModes[] = 'latexml';
612 # Set LaTeXML as default rendering option, because it is nicest
613 $wgDefaultUserOptions['math'] = 'latexml';
617 '''Skippable notes'''
619 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.
622 ''' [[mediawikiwiki:Extension:SpamBlacklist|Extension:SpamBlacklist]]: Import/create IP blacklists, mainly for spam'''
626 if ! grep -F '$wgSpamBlacklistFiles = array(' $mwc &>/dev/null; then
628 $wgEnableDnsBlacklist = true;
629 $wgDnsBlacklistUrls = array( 'xbl.spamhaus.org', 'dnsbl.tornevall.org' );
631 ini_set( 'pcre.backtrack_limit', '10M' );
632 $wgSpamBlacklistFiles = array(
633 "[[m:Spam blacklist]]",
634 "http://en.wikipedia.org/wiki/MediaWiki:Spam-blacklist"
640 ''' [[mediawikiwiki:Extension:TitleBlacklist|Extension:TitleBlacklist]]: Anti-spam '''
643 mw-ext TitleBlacklist
644 if ! grep -F '$wgTitleBlacklistSources = array(' $mwc &>/dev/null; then
646 $wgTitleBlacklistSources = array(
649 'src' => 'MediaWiki:Titleblacklist',
653 'src' => 'http://meta.wikimedia.org/w/index.php?title=Title_blacklist&action=raw',
660 ''' [[mediawikiwiki:Extension:WikiEditor|Extension:WikiEditor]]: Editing box extras and a fast preview tab '''
665 # Enable Wikieditor by default
666 $wgDefaultUserOptions['usebetatoolbar'] = 1;
667 $wgDefaultUserOptions['usebetatoolbar-cgd'] = 1;
669 # Display the Preview and Changes tabs
670 $wgDefaultUserOptions['wikieditor-preview'] = 1;
674 ''' [[mediawikiwiki:CategoryTree|Extension:CategoryTree]]: Enables making nice outlines of pages in a category'''
678 # Mediawiki setting dependency for CategoryTree
683 ''' [[mediawikiwiki:Extension:AbuseFilter|Extension:AbuseFilter]]: Complex abilities to stop abuse '''
685 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:
689 $wgGroupPermissions['sysop']['abusefilter-modify'] = true;
690 $wgGroupPermissions['*']['abusefilter-log-detail'] = true;
691 $wgGroupPermissions['*']['abusefilter-view'] = true;
692 $wgGroupPermissions['*']['abusefilter-log'] = true;
693 $wgGroupPermissions['sysop']['abusefilter-private'] = true;
694 $wgGroupPermissions['sysop']['abusefilter-modify-restricted'] = true;
695 $wgGroupPermissions['sysop']['abusefilter-revert'] = true;
699 '''[[mediawikiwiki:Extension:ConfirmEdit|Extension:ConfirmEdit]]: Custom Captcha'''
701 Uses captchaArray defined in mw_vars.
707 wfLoadExtension( 'ConfirmEdit/QuestyCaptcha' );
708 $wgCaptchaClass = 'QuestyCaptcha';
709 # only captcha on registration
710 $wgGroupPermissions['user' ]['skipcaptcha'] = true;
711 $wgGroupPermissions['autoconfirmed']['skipcaptcha'] = true;
713 if ! grep -Fx 'foreach ( $localSettingsQuestyQuestions as $key => $value ) {' $mwc; then
715 foreach ( $localSettingsQuestyQuestions as $key => $value ) {
716 $wgCaptchaQuestions[] = array( 'question' => $key, 'answer' => $value );
722 Enable account creation that we initially disabled.
724 sed -i "/\\\$wgGroupPermissions\\['\\*'\\]\\['createaccount'\\] = false;/d" $mwc
727 == Additional Configuration with Pywikibot ==
729 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.
732 '''Pywikibot Install'''
734 [[mediawikiwiki:Manual:Pywikibot/Installation|Manual:Pywikibot/Installation]]
739 git clone --recursive https://gerrit.wikimedia.org/r/pywikibot/core.git ~/opt/pywikibot
747 '''Pywikibot Configuration'''
749 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]]
753 cd $HOME/opt/pywikibot
754 dd of=user-config.py <<EOF
756 usernames["$mwfamily"]['en'] = u'$wikiuser'
758 console_encoding = 'utf-8'
759 password_file = "secretsfile"
762 dd of=secretsfile <<EOF
763 ("$wikiuser", "$wikipass")
766 # it won't overrwrite an existing file. Remove if if one exists
767 rm -f pywikibot/families/${mwfamily}_family.py
768 python generate_family_file.py https://$mwdomain/wiki/Main_Page "$mwfamily"
770 # Note, this needed only for ssl site
771 tee -a pywikibot/families/${mwfamily}_family.py<<'EOF'
772 def protocol(self, code):
778 '''Pywikibot Script'''
780 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]].
783 pw="$HOME/opt/pywikibot"
785 dd of=$pw/scripts/${mwfamily}_setup.py<<EOF
789 site = pywikibot.Site()
791 page = pywikibot.Page(site, p)
793 #force is for some anti-bot thing, not necessary in my testing, but might as well include it
794 page.save(force=True)
796 # Small/medium noncommercial wiki should be fine with no privacy policy
797 # based on https://www.mediawiki.org/wiki/Manual:Footer
798 x("MediaWiki:Privacy")
800 # licenses for uploads. Modified from the mediawiki's wiki
801 x("MediaWiki:Licenses", u"""* Same as this wiki's text (preferred)
802 ** CC BY-SA or GFDL| Creative Commons Attribution ShareAlike or GNU Free Documentation License
804 ** Unknown_copyright|I don't know exactly
805 ** PD|PD: public domain
806 ** CC BY|Creative Commons Attribution
807 ** CC BY-SA|Creative Commons Attribution ShareAlike
808 ** GFDL|GFDL: GNU Free Documentation License
809 ** GPL|GPL: GNU General Public License
810 ** LGPL|LGPL: GNU Lesser General Public License""")
811 x("MediaWiki:Copyright", '$mw_license')
812 x("MediaWiki:Mainpage-description", "$mwdescription")
816 # The rest of the settings are for the site style
818 # Remove various clutter
819 x("MediaWiki:Lastmodifiedat")
820 x("MediaWiki:Disclaimers")
821 x("MediaWiki:Viewcount")
822 x("MediaWiki:Aboutsite")
823 # remove these lines from sidebar
824 # ** recentchanges-url|recentchanges
825 # ** randompage-url|randompage
827 x("MediaWiki:Sidebar", """* navigation
828 ** mainpage|mainpage-description
834 # helpfull doc: https://www.mediawiki.org/wiki/Manual:Interface/Sidebar
835 x("mediawiki:Common.css", """/* adjust sidebar to just be home link and up top */
836 /* panel width increased to fit full wiki name. */
837 div#mw-panel { top: 10px; padding-top: 0em; width: 20em }
838 div#footer, #mw-head-base, div#content { margin-left: 1em; }
839 #left-navigation { margin-left: 1em; }
842 /* logo, and toolbar hidden */
843 #p-logo, #p-tb.portal {
847 /* make the font size smaller for the misc stuff */
855 div#mw-content-text {
862 python pwb.py ${mwfamily}_setup
866 ''' Skippable Notes '''
868 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.
870 Family name, and all its duplicattions documented as supposed to be $wgSitename, but it works fine using any name.
872 == Automatic Backups ==
874 Copy this to a file (the next block assumes ~/bin/remote_wiki_backup) on a different machine than the one hosting mediawiki. Also copy ~/mw_vars to the same machine. Setup passwordless sudo to the mediawiki host (specifically, name the host $mwdomain). This will make a versioned backup of the wiki to ~/backup/wiki_file_backup and ~/backup/wiki_db_backup.
880 # if we get an error, keep going but return it at the end
882 trap 'last_error=$?' ERR
884 ssh root@$mwdomain <<ENDSSH
886 $wgReadOnly = 'Dumping Database, Access will be restored shortly';
888 mysqldump -p$dbpass --default-character-set=binary my_wiki > ~/wiki_backup/wikidump
889 sed -i '$ d' $mwc # delete last line
891 rdiff-backup root@$mwdomain::/root/wiki_db_backup ~/backup/wiki_db_backup
892 rdiff-backup root@$mwdomain::$mw ~/backup/wiki_file_backup
897 Run this script on the backup machine to setup daily backups at 4 am.
900 chmod +x $HOME/bin/remote_wiki_backup
904 0 4 * * * x=$($HOME/bin/remote_wiki_backup 2>&1); [[ $? != 0 ]] && echo "$x"
909 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:
911 '''Optional & requires additional steps'''
912 <source lang="bash" type="example">
913 sed -i "/^root:/d" /etc/aliases
914 echo "root: EXAMPLE_ONLY_REPLACE_ME@gmail.com" >> /etc/aliases
918 == Restoring Backups ==
920 '''Whenever you implement a backup system, you should test that restoring the backup works.'''
922 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.
924 To test a backup restore:
925 # Do a backup of your wiki with some content in it, as described in the previous section
926 # Move your mediawiki install directory, or setup Mediawiki on a new machine
927 # Re-execute the mediawiki install steps
928 # Change REPLACE_ME in the code below (as in the backup section so you get the right variables),
929 # Execute the code on the backup machine.
933 HOSTNAME=REPLACE_ME source ~/mw_vars
934 rdiff-backup -r now ~/backup/wiki_file_backup /tmp/wiki_file_restore
935 scp -r /tmp/wiki_file_restore/images root@$mwdomain:$mw/images
936 rdiff-backup -r now ~/backup/wiki_db_backup /tmp/wiki_db_restore
937 scp -r /tmp/wiki_db_restore root@$mwdomain:/tmp
938 ssh root@$mwdomain "mysql -u root -p$dbpass my_wiki < /tmp/wiki_db_restore/wiki_db_dump"
941 Then browse to your wiki and see if everything appears to work.
945 Subscribe to get release and security announcements [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki-announce].
947 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).
949 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]]
951 Minor updates script:
953 s=$HOME/bin/mediawiki_update
959 git checkout origin/$mw_branch
960 git rebase ian/REL1_23-toolbox-in-dropdown
966 git checkout origin/$mw_branch || git checkout -qf origin/master
970 php $mw/maintenance/update.php -q
982 == Upgrading Major Versions ==
984 Reference documentation is at [[mediawikiwiki:Manual:Upgrading]]
988 # Read the "Upgrade notices for MediaWiki administrators" on the upgrade version and any skipped versions at [[mediawikiwiki:Version_lifecycle]].
989 # Setup a blank test wiki with the new version.
990 # Backup the old database, restore it to the new wiki, run php maintenance/update.php.
991 # If everything looks good, repeat and replace the old wiki with the new one.
996 # docs suggests using separate database user, google lead me here for how
997 # https://www.digitalocean.com/community/tutorials/how-to-create-a-new-user-and-grant-permissions-in-mysql
998 mysql -u root -p$dbpass <<EOF
999 CREATE USER 'piwik'@'localhost' IDENTIFIED BY '$piwik_pass';
1000 GRANT ALL PRIVILEGES ON piwik . * TO 'piwik'@'localhost';
1009 Unfortunately, Piwik does not document how to do a fully automated install, and although it certainly seems possible, my first glance at the config file after doing manual steps showed a lot of noise, so we are sticking with the manual steps for now.
1011 In a browser, navigate to your_domain/analytics. Follow these steps [http://piwik.org/docs/installation/#the-5-minute-piwik-installation the-5-minute-piwik-installation], using the database password from the previous section.
1014 We are going to use an extension to handle the javaScript tracking tag part.
1016 Under settings -> user settings, click the cookie to exclude your current browser.
1019 ''' [[mediawikiwiki:Extension:Piwik Integration|Extension:Piwik Integration]] '''
1021 <source lang="bash">
1022 git clone https://github.com/DaSchTour/piwik-mediawiki-extension.git $mw/extensions/Piwik
1025 \$wgPiwikURL = '$mwdomain/analytics/';
1026 \$wgPiwikIDSite = '1';
1031 '''If this is not the first site you setup'''
1033 You will need to adjust the previous $wgPiwikIDSite variable. The correct value can be found in the Piwik javaScript tracking tag code, in the line that looks like <code>_paq.push(['setSiteId', 2]);</code>
1035 '''Automatic Updates'''
1037 Automatically update on tuesday, 3 am server time. This code will create an update script at ~/bin/piwik-remote-update. Based on [http://piwik.org/docs/update/ piwik.org/docs/update].
1039 <source lang="bash">
1040 s=~/bin/piwik-update
1044 piwik_path=$mw/../analytics
1046 wget -q http://builds.piwik.org/piwik.zip
1049 cp \$piwik_path/config/config.ini.php piwik/config
1050 cp -rf piwik/* \$piwik_path
1051 # prevent making an email out of the standard success response
1052 x="\$( \$piwik_path/console core:update )"
1053 if [[ \$x != "Everything is already up to date." ]]; then
1061 teeu "$x" <<< "0 3 * * tue $s"
1066 ''' Skippable Notes '''
1068 Piwik docs say use a subdir or a subdomain. googling finds a page which suggests using a subdomain, for more logical separation https://library.linode.com/web-applications/analytics/piwik/centos-5. However, mediawiki doesn't use the root dir of the web server, so the analytics folder can't mess things up by existing there, and it doesn't have any crazy virtualhost settings which might conflict, so there is no need. Plus we get ssl for free by sharing the same domain.
1070 The docs also say: "When you have finished configuring Piwik, you can set more restrictive permissions (ie. read only) to the “piwik/config/” folder. Piwik will always write its data inside the “piwik/tmp/” folder, so this is the only folder that requires write permissions."
1072 But since the files are already owned by the web server user, and already can't be written by anyone else, it seems a bit of a pointless half measure since the owner can override any permissions. Enabling the .htaccess files seems more useful, which it doesn't even mention.
1074 We could also set up a backup for piwik data, but traffic stat data is not that important so I haven't bothered.
1076 == Choosing Extensions ==
1078 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.
1080 Here are brief descriptions of extensions that are part of distributions and why they were rejected for this wiki.
1082 {| class="wikitable"
1084 | '''InputBox''' || Add html forms to pages. Can't imagine using it. Would install if I did.
1086 | '''Pdfhandler''' || Gallery of pages from a pdf file. Can't imagine using it. Would install if I did.
1088 | '''Footnote''' || deprecated in newer versions
1090 | '''NewUserNotif''' || Send me a notification when a user registers. Seems like an excessive notification.
1092 | '''NewestPages''' || A page creation history that doesn't expire like recent-changes. Meh
1094 | '''RSSReader''' || Embed an rss feed. Can't imagine using it. Would install if I did.
1096 | '''Openid''' || Poor UI. 2 pages & 2 links <login> <login with openid> which is confusing & ugly.
1098 | '''Validator''' || dependency of of semantic
1100 | '''Semantic''' || Seems like a lot of trouble around analyzing kinds of data which my wiki will not have.
1102 | '''wikicalendar''' || Make a calendar of events etc. Can't imagine using it. Would install if I did.
1107 ''' Mediawiki Documentation Quality '''
1109 Overall the documentation is good, but like wikipedia, it depends.
1111 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.
1113 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].
1116 '''Bash here documents, EOF vs 'EOF' '''
1118 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 quoted by \, which itself must then also be quoted to be used literally.
1121 ''' Mediawiki automation tools survey 7/2014 '''
1124 * https://github.com/ianweller/mw
1125 * http://search.cpan.org/~markj/WWW-Mediawiki-Client/bin/mvs
1126 * https://github.com/alexz-enwp/wikitools 3000 lines of code, no response to a bug reports in 2/2014
1128 Getting basic maintenance
1129 * https://github.com/mwclient/mwclient 2000 lines of code
1131 Actively developed, used by wikimedia foundation a lot.
1132 * [[mediawikiwiki:Manual:Pywikibot]]
1135 ''' Troubleshooting Errors '''
1137 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]]
1141 This page and this wiki is licensed under cc-by-sa 4.0.
1142 This means the code is compatible with gplv3.
1144 == todo list for this page ==
1146 * Evaluate any extensions bundled in 27 which I haven't checked out before.
1147 * Update style patch link.
1149 * Upgrade instructions
1150 * Consider changing default signature to not have talk link