2 Using PhpWiki 1.3 with Mac OS X / Darwin
4 PhpWiki works quite well and retains almost complete functionality
5 when used with a default installation of Mac OS X 10.1 (or greater),
6 with only a few minor exceptions as noted below. Setting up a database
7 for the Wiki backend is probably the most difficult part of the
8 PhpWiki installation as it will require use of the Terminal utility;
9 therefore it is recommended that you at least have some familiarity
10 with the unix command prompt. However, the setup is straightforward
11 and you should be able to complete the install by following the
12 instructions in the INSTALL document included with the PhpWiki
15 If you intend to compile the required database software or PHP module
16 yourself you should download and install the Developer tools from
17 Apple, which includes the necessary cc compiler, and at least
18 temporarily activate the superuser (root) account. The steps necessary
19 to do this are relatively more complicated and are beyond the scope of
22 In any case you may find Project Builder to be an attractive
23 alternative to TextEdit, especially if you are intent on heavily
24 customizing PhpWiki, working with PHP or doing any other code
25 development. Among other niceties it provides multiple undos (even
26 beyond the last file save), line numbering and syntax coloring;
27 however it doesn't always properly handle coloring for strangely
28 nested \"escaped quotes\" which are frequently called for in PHP when
29 generating HTML code. \\" <--(kludge for broken syntax coloring)
31 Instructions for using Project Builder with PhpWiki can be found at
32 the bottom of this document.
38 A suitable database for PhpWiki is not included with Mac OS X 10.1. If
39 you decide to use one of the more popular (and free) database packages
40 such as mySQL or PostgreSQL with PhpWiki, fortunately there are
41 precompiled versions of the software available. Some distributions
42 even come with Mac OS X installers which will significantly reduce the
43 amount of work you will have to do in the unix environment.
45 The MySQL 3.23.46 binary installation works well with Mac OS X 10.1
46 and PhpWiki. After you install and test mySQL follow the instructions
47 given in INSTALL.mysql to prepare a new database for use with PhpWiki.
53 The default PHP module for Apache as supplied by Apple does work with
54 PhpWiki but is missing support for the zlib and GD libraries. Wiki
55 will still produce a valid ZIP file when an administrator saves a ZIP
56 dump of the database but it will not use any compression.
58 If you want compressed ZIP dumps you will have to install a version of
59 PHP which does support the zlib library, or compile PHP yourself and
60 replace the default /usr/libexec/httpd/libphp4.so (part of the
61 Apple-supplied Apache installation).
63 PHP with GD library support is required to use "text2png", an
64 experimental plugin for Wiki 1.3.
66 PhpWiki 1.3 already knows where to find the required PEAR.php on Mac
67 OS X systems. However if you need to use PEAR with other PHP
68 applications, edit or create the file /usr/local/lib/php.ini then add
71 include_path = ".:/System/Library/PHP";
73 If you compiled a version of PHP yourself (perhaps newer than the
74 4.0.6 version included by Apple) the path will already be included in
75 the php.ini file. In that case you shouldn't have to change the path,
76 unless you installed PHP into a location other than the default
80 Obtaining and Installing mySQL and libphp4.so
81 ---------------------------------------------
83 Mark Liyanage has graciously provided precompiled Mac OS X versions of
84 mySQL, an updated PHP module for Apache and some installation
85 instructions on his web site. He has also written some tips if you
86 want to compile these programs for yourself.
88 <http://www.entropy.ch/software/macosx/>
90 Note that whether you use the built-in PHP module or another PHP
91 module, it must be activated in Apache's httpd.conf before you can use
92 PHP. Take a look at Mark's PHP installation instructions or read the
93 Apache documentation for more information.
95 A good place to find other distributions of mySQL or PostgreSQL which
96 can be used with Mac OS X are listed at:
98 <http://versiontracker.com/macosx/>
99 <http://fink.sourceforge.net/>
104 The version of PHP 4.1 from Mark Liyanage's web site requires an
105 updated PEAR library. PhpWiki seems to work anyway but it will produce
106 warnings about a depreciated user function with each page load.
108 1. Move the current contents of '/System/Library/PHP' into a backup
109 folder, such as '/System/Library/PHP/PEAR-4.0.6'.
111 2. Take the contents of the 'pear' folder from the official PHP 4.1
112 tarball (php-4.1.0.tar.gz) and move it into '/System/Library/PHP'.
115 PhpWiki Configuration Notes
116 ---------------------------
118 Move the phpwiki folder into the directory used by the web server. In
119 Mac OS X 10.1 this folder will be "/Library/WebServer/Documents"
120 (unless you previously changed it to somewhere else in the config file
121 "/private/etc/httpd/httpd.conf").
123 Follow the generalized installation instructions described in INSTALL
124 but with the changes to sections 1 and 2 listed below.
128 The Mac OS X Apache web server runs as user "www" and this works fine
129 with PhpWiki so long as "Everyone" has at least read-only access in
130 the phpwiki folder's Get Info.
132 If you want to perform serial dumps instead of ZIP dumps you need to
133 set at least one directory to be accessible read-write by the http
134 server. The easiest solution is probably to create a new folder called
135 "dumps" inside the phpwiki folder, then give the user "www" read-write
136 access to it in the terminal:
138 sudo chown www:www /System/Library/phpwiki/dumps
139 sudo chmod u+wrx /System/Library/phpwiki/dumps
143 A few lines need to be inserted into Apache's configuration in order
144 to use "nice" URLs with PhpWiki such as:
146 "http://somehost/wiki/GoodStyle"
148 Open the terminal and type in the following to edit the web server
149 configuration file (enter your administration password when prompted):
151 sudo pico /etc/httpd/httpd.conf
153 Scroll down to the <IfModule mod-alias.c> section. Copy the comment
154 line "#PhpWiki 1.3 aliases" and the four lines below it, then paste it
155 into the mod_alias section as shown below.
157 <IfModule mod_alias.c>
160 # Note that if you include a trailing / on fakename then the server will
161 # require it to be present in the URL. So "/icons" isn't aliased in this
162 # example, only "/icons/". If the fakename is slash-terminated, then the
163 # realname must also be slash terminated, and if the fakename omits the
164 # trailing slash, the realname must also omit it.
166 Alias /icons/ "/usr/share/httpd/icons/"
169 Alias /wiki/themes/ "/Library/WebServer/Documents/phpwiki/themes/"
170 Alias /wiki/themes "/Library/WebServer/Documents/phpwiki/themes"
171 Alias /wiki/favicon.ico "/Library/WebServer/Documents/phpwiki/favicon.ico"
172 Alias /wiki/ "/Library/WebServer/Documents/phpwiki/index.php/"
173 Alias /wiki "/Library/WebServer/Documents/phpwiki/index.php"
176 To save your changes and exit, press 'control-x', then 'y' followed by
179 Restart the Web Sharing server from the System Preferences "Sharing"
180 control panel or from the terminal:
182 sudo apachectl graceful
184 Next, edit the following lines in part five of index.php to match the
187 define('DATA_PATH', '/wiki');
188 define('USE_PATH_INFO', true);
189 define('VIRTUAL_PATH', '/wiki');
193 To retain your PhpWiki logs between system restarts you should specify
194 a non-temporary directory. I recommend you use the same folder where
195 the web-server stores it's logs. Change the following (line 73) in
198 define('ACCESS_LOG', '/tmp/wiki_access_log');
202 define('ACCESS_LOG', '/private/var/log/httpd/wiki_access.log');
204 Note that the automatic /etc/daily and weekly cron cleanup routines
205 will not touch the Wiki log file--even if it is in the same directory
206 as the httpd logs--it will be up to you to Trash it once in a while or
207 write your own /etc/daily.local file to include it as part of a server
210 The web server must have write access to the log file:
212 sudo chown www /private/var/log/httpd/wiki_access.log
215 Using Apple's Project Builder with PhpWiki
216 ------------------------------------------
218 A PB project file is available on the SourceForge CVS server to allow
219 you to easily edit PhpWiki's source code using Apple's Project
220 Builder. PB 2.1 (Dec 2002 DevTools) is recommended. If you have not
221 yet updated to at least PB 1.1.1 (Dec 2001 DevTools) it is highly
222 recommended you do so because the PhpWiki source are written in
223 ISO-8859-1, and some of the bug fixes are pertinent to file encoding.
225 The older PB 1.1 has some bugs which makes it impossible to select the
226 correct character encoding in the GUI for any pre-existing source code
227 files. By using this project file you will find the PhpWiki source
228 files are already preset to use the correct ISO-8859-1 (Western
231 Also by using the project file, if you are updating or adding a
232 tranlastion to the './phpwiki/locale/po/' files, you do not have to
233 run 'make' from the terminal window. The Build Target settings have
234 been preconfigured to automatically build the project with a "legacy
235 Makefile", by invoking '/usr/bin/gnumake' in the folder
236 './phpwiki/locale'. Just click the build button in the toolbar.
238 To download the phpwiki.pbxproj bundle, use CVS to checkout the module
239 named "phpwiki.pbxproj" then place it into the same folder which
240 contains your "phpwiki" folder.
243 How to use SSH with Project Builder
244 -----------------------------------
246 To use the CVS functions in PB, the phpwiki folder itself must have
247 been checked out with CVS (i.e. the 'CVS' folders within each
248 subdirectory of the phpwiki source are required by PB).
250 Project Builder 1.1.1 (December 2001 Dev Tools) can be used with
251 SourceForge's CVS but a little work is needed to get it set up the
252 first time. The following instructions were based on a tip from
257 Make sure that your ssh keys have been uploaded to your account at
258 SourceForge and that you can sucessfully ssh into your account. Next,
259 ensure that you can check out your project from SourceForge using the
260 unix command-line based CVS tools provided by Mac OS X.
264 1. Download and install "keychain" from:
266 <http://www.gentoo.org/projects/keychain.html>
268 Keychain is also available via the Fink package manager.
270 The Keychain script acts as a front-end to ssh-agent, allowing you to
271 easily have one long-running ssh-agent process per system, rather than
272 per login session. This dramatically reduces the number of times you
273 need to enter your passphrase, from once per new terminal window
274 session to once every time your local machine is rebooted. It also
275 allows you to use Project Builder with SSH instead of RSH. SSH is
276 required if you want to commit files to a CVS repository at
279 2. If you use the default tcsh shell or csh, add the following to your
283 alias pb 'open -a /Developer/Applications/Project\ Builder.app '
284 # Alias to servers via SSH
285 alias sshsf 'ssh mysfuserid@phpwiki.sourceforge.net'
287 Also add the following to your ~/.login file:
289 # Keychain is an OpenSSH key manager
290 # This will add my SSH1 and SSH2 key
291 # Use '/sw/bin/keychain' for a fink-installed keychain
292 /usr/bin/keychain ~/.ssh/id_rsa ~/.ssh/id_dsa
293 source ~/.keychain/${HOST}-csh
296 If you use bash instead, add following lines to the ~/.bashrc file:
298 CVS_RSH=ssh; EXPORT CVS_RSH
299 alias pb='open -a /Developer/Applications/Project\ Builder.app '
300 # Alias to servers via SSH
301 alias sshsf='ssh mysfuserid@phpwiki.sourceforge.net'
303 Bash users also add the following to your ~/.login file:
305 # Keychain is an OpenSSH key manager
306 # This will add my SSH1 and SSH2 key
307 /usr/bin/keychain ~/.ssh/id_rsa ~/.ssh/id_dsa
308 source ~/.keychain/${HOSTNAME}-sh
311 3. Close the terminal window then open a new one. Keychain will
312 activate ssh-agent which will ask for your ssh key password. It
313 keeps running in the background and won't ask for your password
314 again until you log out or restart.
316 4. From now on, YOU MUST open Project Builder from the Terminal shell
317 for it's CVS to work with SSH. This is why we created a command
318 alias in .cshrc to launch Project Builder. If it is already
319 running because you double-clicked the PB icon, quit it, then
320 launch it from the terminal by typing pb. <em>Once PB is running
321 you can safely double-click a project file to open it</em>.
323 Using the above method, ProjectBuilder will successfully connect to
324 the Sourceforge CVS with SSH. Any other server which requires cvs
325 connections to be made cia ssh instead of rsh should now work too.
327 Note: Renaming /usr/bin/rsh to something else and replacing it with
328 ssh doesn't seem to work; Project Builder simply MUST be
329 launched from the command line for it to work at all with ssh.
331 Hopefully Project Builder's integrated CVS will be improved in the
332 future to directly support SSH. To let Apple know that full support
333 for SSH in Project Builder is important, send an email to:
335 <macosx-tools-feedback@group.apple.com>
338 Project Builder: Miscellaneous
339 ------------------------------
341 ProjectBuilder 1.1.1 has a new auto-indent feature but it does not yet
342 recognise php files. You can create a temporary file with the filename
343 suffix ".c" and drag it into the project. Paste your code into that temp
344 file to use auto-indent, then copy your changes back to the original file
348 Emacs Users: You can add custom Alt-key bindings to Project Builder
349 for some common Emacs stuff: *Note the wrapped url!
351 <http://developer.apple.com/techpubs/macosx/Cocoa/TasksAndConcepts/
352 ProgrammingTopics/TextDisplay/Tasks/TextDefaultsAndBindings.html>
355 If you have problems after all of this, try contacting the
356 phpwiki-talk list at phpwiki-talk@lists.sourceforge.net.
358 Carsten Klapp <carstenklapp@users.sourceforge.net>
360 $Id: INSTALL.MacOSX,v 1.17 2004-05-09 00:57:31 rurban Exp $