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; but
27 don't rely on PB's text colors too much, it doesn't always properly
28 handle coloring for \"escaped quotes\" which are frequently called for
29 in PHP when generating HTML code.
30 \\" <--(kludge for broken syntax coloring)
32 Instructions for using Project Builder with PhpWiki can be found at
33 the bottom of this document.
39 A suitable database for PhpWiki is not included with Mac OS X 10.1. If
40 you decide to use one of the more popular (and free) database packages
41 such as mySQL or PostgreSQL with PhpWiki, fortunately there are
42 precompiled versions of the software available. Some distributions
43 even come with Mac OS X installers which will significantly reduce the
44 amount of work you will have to do in the unix environment.
46 The MySQL 3.23.46 binary installation works well with Mac OS X 10.1
47 and PhpWiki. After you install and test mySQL follow the instructions
48 given in INSTALL.mysql to prepare a new database for use with PhpWiki.
54 The default PHP module for Apache as supplied by Apple does work with
55 PhpWiki but is missing support for the zlib and GD libraries. Wiki
56 will still produce a valid ZIP file when an administrator saves a ZIP
57 dump of the database but it will not use any compression.
59 If you want compressed ZIP dumps you will have to install a version of
60 PHP which does support the zlib library, or compile PHP yourself and
61 replace the default /usr/libexec/httpd/libphp4.so (part of the
62 Apple-supplied Apache installation).
64 PHP with GD library support is required to use "text2png", an
65 experimental plugin for Wiki 1.3.
67 PhpWiki 1.3 already knows where to find the required PEAR.php on Mac
68 OS X systems. However if you need to use PEAR with other PHP
69 applications, edit or create the file /usr/local/lib/php.ini then add
72 include_path = ".:/System/Library/PHP";
74 If you compiled a version of PHP yourself (perhaps newer than the
75 4.0.6 version included by Apple) the path will already be included in
76 the php.ini file. In that case you shouldn't have to change the path,
77 unless you installed PHP into a location other than the default
81 Obtaining and Installing mySQL and libphp4.so
82 ---------------------------------------------
84 Mark Liyanage has graciously provided precompiled Mac OS X versions of
85 mySQL, an updated PHP module for Apache and some installation
86 instructions on his web site. He has also written some tips if you
87 want to compile these programs for yourself.
89 <http://www.entropy.ch/software/macosx/>
91 Note that whether you use the built-in PHP module or another PHP
92 module, it must be activated in Apache's httpd.conf before you can use
93 PHP. Take a look at Mark's PHP installation instructions or read the
94 Apache documentation for more information.
96 A good place to find other distributions of mySQL or PostgreSQL which
97 can be used with Mac OS X are listed at:
99 <http://versiontracker.com/macosx/>
105 The version of PHP 4.1 from Mark Liyanage's web site requires an
106 updated PEAR library. PhpWiki seems to work anyway but it will produce
107 warnings about a depreciated user function with each page load.
109 1. Move the current contents of '/System/Library/PHP' into a backup
110 folder, such as '/System/Library/PHP/PEAR-4.0.6'.
112 2. Take the contents of the 'pear' folder from the official PHP 4.1
113 tarball (php-4.1.0.tar.gz) and move it into '/System/Library/PHP'.
115 A precompiled PHP 4.1 module for Apache and the PearDB support files
116 are also available at:
118 <http://homepage.mac.com/carstenklapp/>
121 PhpWiki Configuration Notes
122 ---------------------------
124 Move the phpwiki folder into the directory used by the web server. In
125 Mac OS X 10.1 this folder will be "/Library/WebServer/Documents"
126 (unless you previously changed it to somewhere else in the config file
127 "/private/etc/httpd/httpd.conf").
129 Follow the generalized installation instructions described in INSTALL
130 but with the changes to sections 1 and 2 listed below.
132 1. The Mac OS X Apache web server runs as user "www" and this works
133 fine with PhpWiki so long as "Everyone" has at least read-only
134 access in the phpwiki folder's Get Info.
136 If you want to perform serial dumps instead of ZIP dumps you need to
137 set at least one directory to be accessible read-write by the http
138 server. The easiest solution is probably to create a new folder called
139 "dumps" inside the phpwiki folder, then give the user "www" read-write
140 access to it in the terminal:
142 sudo chown www:www /System/Library/phpwiki/dumps
143 sudo chmod u+wrx /System/Library/phpwiki/dumps
145 2. A few lines need to be inserted into Apache's configuration in
146 order to use "nice" URLs with PhpWiki such as:
148 http://somehost/wiki?GoodStyle
150 Open the terminal and type in the following to edit the web server
151 configuration file (enter your administration password when prompted):
153 sudo pico /etc/httpd/httpd.conf
155 Scroll down to the <IfModule mod-alias.c> section. Copy the comment
156 line "#PhpWiki 1.3 aliases" and the four lines below it, then paste it
157 into the mod_alias section as shown below.
159 <IfModule mod_alias.c>
162 # Note that if you include a trailing / on fakename then the server will
163 # require it to be present in the URL. So "/icons" isn't aliased in this
164 # example, only "/icons/". If the fakename is slash-terminated, then the
165 # realname must also be slash terminated, and if the fakename omits the
166 # trailing slash, the realname must also omit it.
168 Alias /icons/ "/usr/share/httpd/icons/"
171 Alias /wiki/images/ "/Library/WebServer/Documents/phpwiki/images/"
172 Alias /wiki/images "/Library/WebServer/Documents/phpwiki/images"
173 Alias /wiki/ "/Library/WebServer/Documents/phpwiki/index.php/"
174 Alias /wiki "/Library/WebServer/Documents/phpwiki/index.php"
177 To save your changes and exit, press 'control-x', then 'y' followed by
180 Restart the Web Sharing server from the System Preferences "Sharing"
181 control panel or from the terminal:
183 sudo apachectl graceful
185 Next, edit the following lines in part five of index.php to match the
188 define('DATA_PATH', '/wiki');
189 define('USE_PATH_INFO', true);
190 define('VIRTUAL_PATH', '/wiki');
192 3. To retain your PhpWiki logs between system restarts you should
193 specify a non-temporary directory. I recommend you use the same
194 folder where the web-server stores it's logs. Change the following
195 (line 73) in index.php from:
197 define('ACCESS_LOG', '/tmp/wiki_access_log');
201 define('ACCESS_LOG', '/private/var/log/httpd/wiki_access.log');
203 Note that the automatic /etc/daily and weekly cron cleanup routines
204 will not touch the Wiki log file--even if it is in the same directory
205 as the httpd logs--it will be up to you to Trash it once in a while or
206 write your own /etc/daily.local file to include it as part of a server
210 Using Apple's Project Builder with PhpWiki
211 ------------------------------------------
213 A PB project file is available on the SourceForge CVS server to allow
214 you to easily edit PhpWiki's source code using Apple's Project
215 Builder. If you have not yet updated to PB 1.1.1 (Dec 2001 DevTools)
216 it is highly recommended you do so because the PhpWiki source are
217 written in ISO-8859-1, and some of the bug fixes are pertinent to file
220 PB 1.1 has some bugs which makes it impossible to select the correct
221 character encoding in the GUI for any pre-existing source code
222 files. By using this project file you will find the PhpWiki source
223 files are already preset to use the correct ISO-8859-1 (Western
226 Also by using this file, if you are updating or adding a tranlastion
227 to the './phpwiki/locale/po/' files, you do not have to run 'make'
228 from the terminal window. The Build target settings have been
229 preconfigured to automatically build the project with a "legacy
230 Makefile", by invoking '/usr/bin/gnumake' in the folder
231 './phpwiki/locale'. Just click the build button in the toolbar.
233 To download the phpwiki.pbxproj bundle, use CVS to checkout the module
234 named "phpwiki.pbxproj" then place it into the same folder which
235 contains your "phpwiki" folder.
238 How to use SSH with Project Builder
239 -----------------------------------
241 Project Builder 1.1.1 can be used with Sourceforge's CVS but there is
242 a little bit of work to get it set up the first time. The following
243 instructions were based on a tip from macosxhints.com.
247 Checkout phpwiki with the cvs command line tools. Make sure that your
248 ssh keys have been uploaded to your account at Sourceforge and that
249 you can sucessfully ssh into phpwiki.sourceforge.net.
253 1. Download and install "keychain" from:
255 <http://www.gentoo.org/projects/keychain.html>.
257 The Keychain script acts as a front-end to ssh-agent, allowing you to
258 easily have one long-running ssh-agent process per system, rather than
259 per login session. This dramatically reduces the number of times you
260 need to enter your passphrase, from once per new terminal window
261 session to once every time your local machine is rebooted.
263 2. Add the following to your .cshrc file (if you use the default tcsh
267 # Keychain is an OpenSSH key manager
268 # This will add my SSH1 and SSH2 key
269 /usr/bin/keychain ~/.ssh/id_rsa ~/.ssh/id_dsa
270 source ~/.ssh-agent-csh-${HOST}
271 # Alias to servers via SSH
272 alias sshsf 'ssh mysfuserid@phpwiki.sourceforge.net'
274 (bash users would substitute the following lines in the above script
275 for their .bashrc file:)
277 CVS_RSH=ssh; EXPORT CVS_RSH
278 source ~/.ssh-agent-${HOSTNAME}
279 alias sshsf='ssh mysfuserid@phpwiki.sourceforge.net'
281 3. Close the terminal window then open a new one. Keychain will
282 activate ssh-agent which will ask for your ssh key password. It
283 keeps running in the background and won't ask for your password
284 again until you log out or restart.
286 4. From now on, YOU MUST open Project Builder from the Terminal shell
287 for it's CVS to work with SSH. This is why We created a command
288 alias in .cshrc to launch Project Builder. If it is already running
289 because you double-clicked the PB icon, quit it, then launch it
290 from the terminal by typing pb. Once PB is running you can safely
291 double-click a project file to open it.
293 Using the above method, ProjectBuilder will successfully connect to
294 the Sourceforge CVS with SSH. Any other server which requires cvs
295 connections via ssh instead of rsh should work too.
297 Note: Renaming /usr/bin/rsh and replacing it with ssh doesn't seem to
298 work; Project Builder simply MUST be launched from the command line
299 for it to work at all with ssh.
301 Hopefully SSH support will be improved in the future. Send an email
302 to: macosx-tools-feedback@group.apple.com to let the team know that
303 full support for SSH in Project Builder is important.
306 Emacs Key Bindings for Project Builder
307 --------------------------------------
309 Emacs Users: You can add custom Alt-key bindings to Project Builder
310 for some common Emacs stuff: *Note the wrapped url!
312 http://developer.apple.com/techpubs/macosx/Cocoa/TasksAndConcepts/
313 ProgrammingTopics/TextDisplay/Tasks/TextDefaultsAndBindings.html
316 If you have problems after all of this, try contacting the
317 phpwiki-talk list at phpwiki-talk@lists.sourceforge.net.
322 $Id: INSTALL.MacOSX,v 1.11 2001-12-31 01:46:04 carstenklapp Exp $