Manual:Running MediaWiki on macOS

< MediaWiki User's Guide: Running MediaWiki

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

These instructions have only been tested with 10.2 and 10.3.

Apache
The Apache webserver is included in Mac OS X. It can be found in System Preferences &mdash; Sharing &mdash; Services. Apache is referred to as Personal Web Sharing there. Tick its checkbox or press the Start button to launch it.

Security note:

By default the included Apache configuration will serve pages to anyone who can open a network connection to your machine. If you have the firewall on, it will punch port 80 open in order to make the web serving public. To avoid any security breaches, you will thus need to manually edit Apache's configuration later, stay tuned.

MySQL

 * MySQL should be preinstalled on Mac OS X Server 10.2 or Mac OS X Server 10.3.


 * If you're using Mac OS X Client 10.2 (or higher), you can either:


 * Get the Complete MySQL install package. This package allows you to configure MySQL with a nice PreferencePane in System Preferences, "the Mac way". It's free software like the standard package mentioned below.
 * If you're in danger of your new database being hacked, make sure you're going to be alone on the machine until it's configured.
 * Inside the downloaded disk image is an installer. Run it.
 * The preference pane has to be installed manually: Copy the file "MySQL.prefPane" to the folder "PreferencePanes" inside the folder "Library" inside your home folder. If the folder "PreferencePanes" doesn't exist yet, create it.
 * Open System preferences and you will see a new prefence pane called "MySQL", click it, then click on "Initialize". (You may get prompted for your password here.) It's important that you don't click on "Start" yet: That would kind-of start up MySQL, but it wouldn't work correctly. And even worse, a program bug will prohibit you from clicking "initalize" in this case. If you've made this mistake and clicked "Start", just restart your machine and you get another chance to press the "Initialize" button.
 * Having initialized MySQL, you should now click "Start". (If the server fails to start, check that the /tmp directory permissions are set correctly. You can ensure this by typing "sudo chmod 1777 /tmp" from the command line.)
 * Finally, click "Set Root Password". The inital password is "nothing", so leave the first field empty and enter something in the other two.


 * Database password caveat:
 * The only MySql database prerequisite is the MySQL root password (which you've just set). It is needed for the installation below.


 * - or -


 * Get the install package from mysql.com. This is the "standard" MySQL package, however note that it is probably the less convenient option (no Preference Pane, so you have to know what's what).
 * Again, if you're in danger of your new database being hacked, make sure you're going to be alone on the machine until it's configured.
 * There are two installer packages, one for MySQL and one for installing a StartupItem. The latter is for MySQL to launch as a server at system startup (which you could also have told it to do via the PreferencePane using the other method &mdash; toldyer that would've been easier ;-). You need to run both installers.
 * After installing, you still need to secure the default accounts; if you don't, anyone can log into your database with full privileges (considered to be a Bad Thing&trade;).

Mac OS 10.2 (jaguar)
On Mac OS X 10.2, you'll need to install PHP. There is an installable package here: http://www.entropy.ch/software/macosx/php/. At the time of this writing, the two most recent available versions there were PHP 4.3.6 and PHP 5.0.1. The problem with PHP5 is that there currently still is an incompatibility between the monobook skin and PHP5, causing MediaWiki to revert to an older look and feel if you use the newer PHP. Thus, you probably want to go for the PHP4 installer.

You can install from source too, of course, if you're a Unix-loving masochist.

Mac OS 10.3 (panther)
On Mac OS X 10.3, PHP is installed by default but not enabled. If you choose to use GD library (see below), you could, for convenience, still use the PHP installers mentioned in the Jaguar section above, as they include GD library. It won't hurt your system using these installers, even though you've already got PHP. (But the hints regarding PHP4/5 still apply!) However, GD library is not recommended (again see below), so you probably want to simply enable your existing PHP installation:

To do so, you just need to edit this file:

Uncomment (remove the preceding # characters from) the lines that contain

and

Then open the Sharing panel in System Preferences and stop and restart personal web sharing.

Another method that needs further investigation: uncomment lines in /etc/httpd/users/php.conf

Graphics libraries
MediaWiki's image thumbnailing requires either ImageMagick or GD library to work and neither are installed by default. This is not strictly required software in that you can install MediaWiki without either of the two and it will work &mdash; only the image thumbnailing feature will not function.

If you're unsure whether you've got GD library or ImageMagick installed, you could simply proceed to "Setting up MediaWiki" &mdash; at the start of the process, MediaWiki will tell you if they're there or not and if they aren't you can still install them (as follows) before proceeding with the MediaWiki install proper.

GD library produces poorer thumbnails than ImageMagick, so the latter is recommended. Note however that MediaWiki will currently use GD library (and not ImageMagick) if both are installed. (So there is merit in not even installing GD library.)

To get MediaWiki to use ImageMagick despite GD being installed, you would need to edit the LocalSettings.php file in your MediaWiki directory after installation &mdash; you would need to change these lines:

$wgUseImageResize = true;
 * 1) $wgUseImageMagick = true;
 * 2) $wgImageMagickConvertCommand = "/usr/bin/convert";

to this:

$wgUseImageResize = true; $wgUseImageMagick = true; $wgImageMagickConvertCommand = "/usr/local/bin/convert";

Again, you should not have to do this if GD library was not installed during MediaWiki installation or if you're happy to use it.

GD library
As already mentioned, the PHP installers mentioned in the Jaguar section above include GD library, so if you used them and are happy enough with GD library then you can skip the rest of this section.

If you didn't use the said PHP installers/wish to install GD library seperately, you could try installing it from http://www.boutell.com/gd/.

ImageMagick
The probably most convenient and Mac-alike way to install ImageMagick is by using the installer from the Entropy site (the same site that offered the PHP installers above). You can also install ImageMagick through Fink or DarwinPorts.

Web-based setup

 * 1) Get MediaWiki sources from http://sourceforge.net/projects/wikipedia/.
 * 2) Untar the file in a temporary folder. (It's a good idea to refer to the INSTALL document in this folder.)
 * 3) click on the config directory in the mediawiki folder and type Apple-I (get info) change the directories permissions so that php and apache can edit the contents (you can set it so everyone can read and write this folder but if you do this you must make sure you set it back when you have finished installing)
 * 4) Move the directory somewhere web-accessible and go there with your browser. For an installation on non-server Mac OS X versions, this would typically be the "Sites" folder (which should be in your home directory). You might like to use a subdirectory of "mediawiki" to make sure your wiki doesn't get mixed in with anything else. These instruction will assume you did this. &mdash; If you chose a different path, you will need to make applicable changes.
 * 5) Browse to http://localhost/~short_username/mediawiki/ (where short_user name is your short username) This will redirect you to the installer.
 * 6) MediaWiki may complain right that it can't find ImageMagick or GD library. If so, then see above.
 * 7) Follow the instructions to install: Fill in the details it asks for and wait while the installer does its work.
 * 8) When that finishes, you should be prompted to copy your LocalSettings.php file: In the mediawiki folder, again locate the directory called "config". Open this directory and copy of "LocalSettings.php" to the mediawiki folder.
 * 9) Eventually, you should be led to http://localhost/~short_username/mediawiki and you should see a nice new wiki waiting to be populated.
 * 10) If all of the above has worked, you should then DELETE the said config folder, for security reasons.

Note: With MySQL 4.1 and above, you might run into the "Couldn't connect to database" error. This is due to the new authentication protocol in MySQL. The remedy is to reset the user (root, and after creation the wikiuser as well) to use an old-protocol password, as described in the MySQL manual (Appendix A, chapter "Client does not support authentication protocol error"). In the longer term, MediaWiki should probably update the client library... MySQL manual page [


 * Do you mean that PHP needs an updated MySQL client library, or that something in MediaWiki's code needs to be changed?

Securing/configuring Apache
Create a text file named " " in.

The file should contain the following lines (modify them as applicable!):

Alias /wiki "/Users/YOUR-HOME-FOLDER/Sites/mediawiki"

 Options Indexes MultiViews FollowSymLinks AllowOverride None Order allow,deny Allow from all 

 AllowOverride None AddType text/plain .html .htm .shtml # php_admin_flag engine off # This doesn't seem to work. 

RewriteEngine on  RewriteRule ^/wiki/en/(.*)$ /mediawiki/wiki.phtml?title=$1

(You may have to create the above .../upload folder for file uploads to work.)


 * On 10.3, you can simply create.
 * On 10.2, you may need to add this line to the bottom of :

Include /etc/httpd/users/wiki.conf

That done, restart Apache. Restart it manually to make sure it reports any errors to you:

sudo apachectl restart

(If you restart it from the Sharing panel and there's a config error, it'll just sit there mute. Very annoying.)

Make sure that the .phtml extension is assigned to PHP as well as .php; there should be a line like this in the  file:

AddType application/x-httpd-php .php .phtml

Security note: Unless you've disabled uploads, do not forget to disable PHP in the upload directory.
 *  Presumably the above  line is supposed to do this? 

Enabling email
To send outgoing mail (inter-user messages and password reminders) a mail server needs to be running.

The mail server on 10.2 is sendmail, but is misconfigured in OS X client and won't run by default. 

On 10.3 postfix is the default mail server; to enable it see

Caveats

 * The HFS+ filesystem is not case-sensitive, but MediaWiki is in various places. There conceivably may be problems relating to this. However, with Mac OS X Server you can format a disk as Case-sensitive HFS+.
 * If your wiki is configured as Latin-1, you cannot upload images with non-ASCII characters in their file names (362).

Additional info
The following sections are advanced information and describe an alternative (not necessarily better) choice of a MediaWiki install tree. They are included here so that advanced users may obtain additional information about which files are relevant for what.

Alternative directory layout
On my machine I've installed them under /Library/MediaWiki like so:

/Library/MediaWiki/wiki.conf A bit of Apache configuration, see below

/Library/MediaWiki/php the *.php files from include/ and languages/ /Library/MediaWiki/cache /Library/MediaWiki/tmp <- temp files for TeX (?) For file cache and TeX temp files (if using). If using, must be writable by the www group.

/Library/MediaWiki/web Here's where the web-exposed stuff will go: wiki.phtml redirect.phtml LocalSettings.php style/ upload/ math/

Alternative Apache configuration
The 'wiki.conf' might look something like this:

Alias /wiki "/Library/MediaWiki/web"

 Options Indexes MultiViews FollowSymLinks AllowOverride None Order allow,deny Allow from all 

 AllowOverride None AddType text/plain .html .htm .shtml php_admin_flag engine off 

RewriteEngine on  RewriteRule ^/wiki/en/(.*)$ /wiki/wiki.phtml?title=$1

Another way to get Apache/MySQL/PHP set up
For a personal Wiki environment, you may find it easier to install MAMP. This installer will provide its own Apache, MySQL and PHP (with MMCache and Zend Optimizer) 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 /Users/yourname/public_html instead of the Mac's usual /Users/yourname/Sites. MAMP will open up your browser and show you how things are configured.

Just untar the package as above into your public_html, point your browser there, and you should have your wiki up and running in a few minutes after filling in the configuration form.

Next page: Running MediaWiki on FreeBSD >