Manual:Running MediaWiki on macOS

The primary development and deployment environment for MediaWiki is on Linux and Unix systems; Mac OS X is Unix under the hood, so it's fairly straightforward to run it.

Get requirements

Manual:Installation guide

Instead of setting the required software up separately you might be better off to start with MAMPstack + MediaWiki, which gives you Apache, MySQL, PHP & MediaWiki in one convenient package.

Or use XAMPP Application to get easier Installation and highly recommended for beginners, go here instead.

MAMP

For a personal Wiki environment, you may find it easier to install MAMP, if you are using Mac OS X 10.4 or newer (MAMP will not run on Mac OS X 10.3 or older). This installer will provide its own Apache, MySQL and PHP and a nice simple control panel, running under your login (in other words, this really isn't configured to work as a production server, so don't do that). If you turn off the Mac's built-in personal web server, you can run MAMP's Apache on port 80.

You will still need to install ImageMagick, but otherwise everything MediaWiki needs will be there. Note that with MAMP your personal Web directory defaults to /Applications/MAMP/htdocs instead of the Mac's usual /Users/yourname/Sites. If you don't want to store your own data files in the Applications directory, open MAMP's Preferences, select the Apache tab, and change the document root to the directory of your choice. /Users/yourname/Sites is an excellent choice. Clicking on MAMP's Open Start page button will open http://localhost:8888/MAMP/ in your browser to show you how things are configured.

You should also make sure to update $wgDBserver within your LocalSettings.php file to point to the right MySQL unix socket file:

- $wgDbServer = "localhost";
+ $wgDbServer = "localhost:/Applications/MAMP/tmp/mysql/mysql.sock";

Install MediaWiki

Manual:Installation guide

TeX support

See Manual talk:Running MediaWiki on Mac OS X#Mathematics for explicit instructions on how to add TeX support for macOS.

Homebrew Setup

Prerequisites

• Homebrew installed
• Gerrit account set up
• If MediaWiki was previously set up with Docker:
  • Create a new directory to clone MediaWiki into (allowing for parallel setups so that each can have its own LocalSettings.php)
  • Stop the container (both this and Docker setups run on 8080 port so there could only be one running at any given time)

Steps

1. Create empty mediawiki directory, download MediaWiki from Git into w folder inside mediawiki folder
2. Install Composer

   brew install composer
   

3. Update MediaWiki dependencies composer update --no-dev from within the folder w.
4. Set up PHP, Apache, MariaDB, Redis, ElasticSearch (Docker) locally and update Apache config per https://www.kostaharlan.net/posts/mediawiki-homebrew-php/. N.b. PHP 7.4 is not well-supported by Homebrew, run "brew install php@8.1"
5. Start services

   brew services start php@8.1 # php7.4 is not well-supported in homebrew anymore
   brew services start httpd
   brew services start mariadb
   brew services start redis
   

6. Make sure all services are running (by running brew services and docker ps for ElasticSearch) & navigate to localhost:8080/wiki/index.php
7. Go through MediaWiki installation steps (installation link is at the bottom of the page), at the end of the process, save LocalSettings.php to the project directory (mediawiki/w)
8. After these steps, there should be a barebone MediaWiki installation (no skins/styling/data) at localhost:8080.

ElasticSearch

ElasticSearch is also installable via homebrew, but it won't have the wikimedia/search/highlighter/experimental-highlighter-elasticsearch-plugin or wikimedia/search/extra plugins. Running ElasticSearch as a Docker container is a good option:

docker run -d --restart=always -v elasticdata:/usr/share/elasticsearch/data -e "discovery.type=single-node" -e "bootstrap.system_call_filter=false" -p 9200:9200 -p 9300:9300 docker-registry.wikimedia.org/dev/cirrus-elasticsearch:7.10.2-s0

If you are on an Apple silicon system, you will want to use the kostajh/wmf-elasticsearch-arm64 image that is built for arm64. See more setup instruction in MediaWiki-Docker/Configuration recipes/ElasticSearch (although you can ignore the Docker-Compose snippet there)

Setting up XDebug with PhpStorm

1. Install Xdebug via pecl, with pecl install xdebug
2. Add xdebug.mode=debug and xdebug.client_port=9000 to php.ini (check the config file path by running php --ini)
3. Verify Xdebug shows up when running php --version
4. Restart Apache & PHP

   brew services restart httpd
   brew services restart php@8.1
   

5. In PhpStorm: Preferences > Languages & Frameworks > PHP > CLI interpreter > PHP executable > Select Homebrew PHP path (for example /usr/local/Cellar/php@8.1/8.1.{version}/bin/php), make sure debug port includes 9000
6. Install Xdebug browser extension
7. In PhpStorm: Listen for PHP Debug Connections (phone icon on top right)
8. Verify setup in PhpStorm: PhpStorm > Run > Web Server Debug Validation > Enter http://localhost:8080/w/ for “Url to validation script”

composer can get stuck at a breakpoint in PhpStorm after enabling Xdebug this way. Check the PhpStorm debug console if composer commands are taking a long time!