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
editInstead 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
editFor 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
editTeX support
editSee Manual talk:Running MediaWiki on Mac OS X#Mathematics for explicit instructions on how to add TeX support for macOS.
Homebrew Setup
editPrerequisites
edit- 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)
- Create a new directory to clone MediaWiki into (allowing for parallel setups so that each can have its own
Steps
edit- Create empty
mediawiki
directory, download MediaWiki from Git intow
folder inside mediawiki folder - Install Composer
brew install composer
- Update MediaWiki dependencies
composer update --no-dev
from within the folder w. - 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"
- 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
- Make sure all services are running (by running
brew services
anddocker ps
for ElasticSearch) & navigate tolocalhost:8080/wiki/index.php
- 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
) - After these steps, there should be a barebone MediaWiki installation (no skins/styling/data) at
localhost:8080
.
ElasticSearch
edit
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
edit- Install Xdebug via
pecl
, withpecl install xdebug
- Add
xdebug.mode=debug
andxdebug.client_port=9000
tophp.ini
(check the config file path by runningphp --ini
) - Verify Xdebug shows up when running
php --version
- Restart Apache & PHP
brew services restart httpd brew services restart php@8.1
- 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 includes9000
- Install Xdebug browser extension
- In PhpStorm: Listen for PHP Debug Connections (phone icon on top right)
- 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!