Difference between revisions of "Help:Running MediaWiki on Mac OS X"

Revision as of 05:34, 19 July 2006

< 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, 10.3 and, to a limited extent (i.e. they work, but the text has not been updated to specifically refer to this), 10.4.

Required software

Apache

The Apache webserver is included in Mac OS X. It can be found in System Preferences — Sharing — 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 is preinstalled on Mac OS X Server.

If you're using Mac OS X Client 10.3 or below, 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.
1. If you're in danger of your new database being cracked, make sure you're going to be alone on the machine until it's configured.
2. Inside the downloaded disk image is an installer. Run it.
3. The preference pane has to be installed now. Double-click on MySQL.prefPane in the disk image and choose whether to install it for all users or just you.
4. 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", reclick on the MySQL.prefpane file to start over. If this fails, just restart your machine and you get another chance to press the "Initialize" button.
5. 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.)
6. 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 -

The 5.0 install package from mysql.com is suitable for 10.3 and 10.4, whilst the 4.0 install package works only with 10.3. These are the "standard" MySQL package. Note that the 4.0 version does not have a Preference Pane. Version 5.0 is preferred.
1. 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.
2. 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 — toldyer that would've been easier ;-). You need to run both installers.
3. 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™).

Troubleshooting

If you have problems with MySQL you should try to uncheck the "Automatically Start MySQL on Startup"-Button, restart your Computer and start it by hand because it can sometimes be confusing if it does not work as expected.
Upgrading Mysql can also be a Problem, check if more than one MySQL process is running.

PHP

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. Seems to have been fixed in the latest PHP5 or MediaWiki.

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:

/etc/httpd/httpd.conf

Use the terminal program (Applications/Utilities), open a new shell (command-N), and type: cd /etc/httpd/

then

pico httpd.conf

this will open up a simple text editor with commands (^ means control key) at the bottom

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

"LoadModule php4_module libexec/httpd/libphp4.so"

and

"AddModule mod_php4.c".

When you press Control-X you are asked if you want to save the changes, press Y to answer Yes. Now you will exit the program and your changes are saved. If you are unable to save the file after making edits, start over by typing

sudo pico httpd.conf

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

Mac OS 10.4 Server (Tiger)

On Mac OS 10.4 Server (Tiger), PHP is preinstalled but not enabled. To enable it, use the Server Admin GUI.

In Server Admin, go to Web > Settings > Modules, check off php4_module, then click Save.

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 — 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" — 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 — you would need to change these lines:

$wgUseImageResize  = true;
# $wgUseImageMagick = true;
# $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 separately, 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.

Setting up MediaWiki

Web-based setup

Get MediaWiki sources from http://sourceforge.net/projects/wikipedia/.
Untar the file in a temporary folder. (It's a good idea to refer to the INSTALL document in this folder.)
Click on the config directory in the mediawiki folder and type Apple-I (get info); then, change the directory's permissions so that everyone can write to it. (This change in permission is insecure, but you'll be deleting the directory in a moment anyway.)
Move the mediawiki directory to your "Sites" folder in your home directory.
Browse to http://localhost/~short_username/mediawiki/ (where short_user name is your short username) You will see the mediawiki installer. If you don't get the page, go to the apple Preferences and check that web sharing is on.
MediaWiki may complain right that it can't find ImageMagick or GD library. If so, then see above.
Follow the instructions to install: Fill in the details it asks for and wait while the installer does its work. (Specific advice about the database items, e.g. usernames, would help here...can someone add this? )
Unless the version of your database is compatible with the version assumed in the mediawiki setup, the above steps will produce an error about connecting to the database. This results from an incompatibility in the password format stored in the mysql database. You need to fix this problem by the following steps.
1. run 'mysql' as the root mysql user (ie 'mysql -su root -p').
2. type 'SELECT Host, User FROM mysql.user;'. You should get a list of hosts and users. Look for lines with wikiuser in them.
3. type (for each host wikiuser has) 'SET PASSWORD FOR 'wikiuser'@'localhost' = OLD_PASSWORD('password');'.
  1. note: i couldn't get these instructions to work, but i went to this page http://www.macdevcenter.com/pub/a/mac/2005/09/20/apache.html?page=2 and did the database install section and then ran the mediawiki setup again and it worked perfectly
Connection errors may also occur if your mysql socket file mysql.sock is in an unexpected place. You will see Connecton failed next to SQL server host and error Can't connect to local MySQL server through socket '/var/mysql/mysql.sock'. To fix this, you can modify your /etc/php.ini file (if you don't have one, you can create it from /etc/php.ini.default) so that mysql.default_socket points to the correct location.[1] [2]
As promted by the webpage, copy the LocalSettings.php file from the config folder up one level, to the mediawiki folder.
Eventually, you should be led to http://localhost/~short_username/mediawikiand you should see a nice new wiki waiting to be populated.
Once this is working, or if you give up and have to leave it for more than a few minutes, change the permissions of the config folder to prevent reading by anyone. If the wiki is working, you may as well just delete this folder.

Mac OS X 10.4 Server (Tiger)

On Mac OS X 10.4 Server (Tiger), Apple provides an application to enable MySQL, set the root MySQL password, and start the MySQL service. You can find this app in /Applications/Server/MySQL Manager.app. See this article at Apple Support for more details.

If you're having trouble getting PHP to talk to MySQL, see article 301457 at Apple Support.

In the MediaWiki install web page, the MySQL server name must specify the fully qualified domain name of your server (change it from 'localhost' to your server's name, foo.bar.com).

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 users which connect to the MySQL server (DB root, and after creation the DB user, wikiuser is the default name, 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 its client library... MySQL manual page

I wonder if someone could write the requisite mysql commands here? I fear that the mysql steps are daunting (and uninteresting) enough to discourage folks who might otherwise to share interesting information using mediawiki. Ideally, the mediawiki system itself should explain this, probably on that first setup webpage, but until that happens, perhaps we can help each other on this site ... --DK 23:01, 2005 July 29 (UTC)

In 10.4.4 (and following, I suppose) the following Terminal commands successful reestablish the link between MySQL and PHP:

$ sudo mkdir /var/mysql
$ sudo ln -s /tmp/mysql.sock /var/mysql/mysql.sock

-Edonovan (from Wikipedia) 2006 March 30

In OS X 10.4.X Tiger, the preinstalled MySQL may also fail to recognize "localhost" as a valid host. In the web-based installer, try "servername.local" instead of "localhost", where servername=the computer name. If you are using Server Admin, this is the same as the Local Hostname setting. The web based installer for 1.5X and 1.6X through 1.6.7 will then fail at Initialising the Mediawiki namespace. This is because it is trying to connect as the wikiuser defined by the installer, but it is attempting to use localhost. Go into MySQL and change the host for the wikiuser and it will all work. MediaWiki should probably adjust the installer to create the wikiuser with the correct local hostname. - JimHu 18:46, 23 June 2006 (UTC)

Securing/configuring Apache

Create a text file named "wiki.conf" in /etc/httpd/users.

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

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

 <Directory "/Users/YOUR-HOME-FOLDER/Sites/mediawiki">
       Options Indexes MultiViews FollowSymLinks
       AllowOverride None
       Order allow,deny
       Allow from all
 </Directory>

 <Directory "/Users/YOUR-HOME-FOLDER/Sites/mediawiki/upload">
    AllowOverride None
    AddType text/plain .html .htm .shtml
 # php_admin_flag engine off  # This doesn't seem to work.
 </Directory>

  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 /etc/httpd/users/wiki.conf.
On 10.2, you may need to add this line to the bottom of /private/etc/httpd/httpd.conf:

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 /etc/httpd/httpd.conf 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 php_admin_flag engine off line is supposed to do this?

I think so. I made it work by removing the comment "#This doesn't seem to work".

Enabling uploads

Uploads are disabled by default for security reasons.

Before you do this, please make sure that your upload directory is configured in a safe manner so it's not possible to upload and execute arbitrary PHP code. Otherwise, someone could upload a PHP file, and might be able to do all sorts of horrible things like delete your entire website.

To enable uploads, uncomment the following line in LocalSettings.php and make sure it is set to true:

# $wgEnableUploads = true;

You will also need to enable uploads from PHP; set the following in php.ini:

file_uploads = On

Earlier versions of MediaWiki included a bug that potentially allows logged- in users to delete arbitrary files in directories writable by the web server user by manually feeding false form data; this is now fixed.

To disable uploads, comment out or set the following option to false in LocalSettings.php:

$wgEnableUploads = true;

Notes: Some httpd.conf config files have this line by default:

Alias /images/ /usr/share/images/

It will break the access to images/ folder in MediaWiki. To prevent this, either change the default upload directory or remove this line.

Be sure that you can write to the directory- check ownership, permissions, and any other restrictions which could prevent you from writing to the directory in question (including PHP security settings such as open_basedir).

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. [3]

On 10.3 postfix is the default mail server; this post on macosxhints.com tells how to enable it.

An alternative on OS X 10.3 is to use Postfix Enabler (shareware), which has a user-friendly Mac GUI.

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+.
As with all other OS X software, it's probably a good idea to repair the permissions using Disk Utility once you're finished installing.
If your wiki is configured as Latin-1, you cannot upload images with non-ASCII characters in their file names (bugzilla: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"

 <Directory "/Library/MediaWiki/web">
       Options Indexes MultiViews FollowSymLinks
       AllowOverride None
       Order allow,deny
       Allow from all
 </Directory>

 <Directory "/Library/MediaWiki/web/upload">
    AllowOverride None
    AddType text/plain .html .htm .shtml
    php_admin_flag engine off
 </Directory>

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

MAMP - An easier 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 eAccelerator (an updated 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 /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.

Installation of MediaWiki is simple:

Untar the MediaWiki package as above into your Sites folder
Change the name of the folder to something simple like mediawiki
Change the permissions of MediaWiki's config folder so that it is writeable by everyone
Open http://localhost:8888/mediawiki/config/index.php
Fill in the blanks on the initialization form
Click Install and wait...be very patient
When done, copy LocalSettings.php from the config folder to it's parent folder
You can now delete the config folder

That's it! Open MediaWiki by pointing your browser to http://localhost:8888/mediawiki/index.php. You should have your wiki up and running in a few minutes after filling in the configuration form.

On Mac OS X 10.4 Tiger, you can easily make Apache and MySQL start automatically upon login. See these instructions at MAMP's forums.

TeX support

See

math/README

in the distribution.

The README above doesn't help much. See Talk:Running_MediaWiki_on_Mac_OS_X#Mathematics for explicit instructions on how to add TeX support for MacOS X.

Once you have added this support, until (if) MediaWiki is updated, you may want to look at TeX#TeX for instructions on how to modify your setup to get TeX pngs that are transparent (so look good against a grey background), scale in size to match the surrounding text, and are vertically aligned properly with surrounding text.

Maynard Handley 12:44, 24 July 2005 (UTC)

Troubleshooting

see Discussion

Other resources

Next page: Running MediaWiki on FreeBSD >