doc/INSTALL.MacOSX

   1 Using PhpWiki 1.3 with Mac OS X / Darwin
   2
   3 PhpWiki works quite well and retains almost complete functionality
   4 when used with a default installation of Mac OS X 10.1 (or greater),
   5 with only a few minor exceptions as noted below. Setting up a database
   6 for the Wiki backend is probably the most difficult part of the
   7 PhpWiki installation as it will require use of the Terminal utility;
   8 therefore it is recommended that you at least have some familiarity
   9 with the unix command prompt. However, the setup is straightforward
  10 and you should be able to complete the install by following the
  11 instructions in the INSTALL document included with the PhpWiki
  12 download.
  13
  14 If you intend to compile the required database software or PHP module
  15 yourself you should download and install the Developer tools from
  16 Apple, which includes the necessary cc compiler, and at least
  17 temporarily activate the superuser (root) account. The steps necessary
  18 to do this are relatively more complicated and are beyond the scope of
  19 this document.
  20
  21 In any case you may find Project Builder to be an attractive
  22 alternative to TextEdit, especially if you are intent on heavily
  23 customizing PhpWiki, working with PHP or doing any other code
  24 development. Among other niceties it provides multiple undos (even
  25 beyond the last file save), line numbering and syntax coloring; but
  26 don't rely on PB's text colors too much, it doesn't always properly
  27 handle coloring for \"escaped quotes\" which are frequently called for
  28 in PHP when generating HTML code.
  29
  30 Instructions for using Project Builder with PhpWiki can be found at
  31 the bottom of this document.
  32
  33 Database
  34 --------
  35 A suitable database for PhpWiki is not included with Mac OS X 10.1. If
  36 you decide to use one of the more popular (and free) database packages
  37 such as mySQL or PostgreSQL with PhpWiki, fortunately there are
  38 precompiled versions of the software available. Some distributions
  39 even come with Mac OS X installers which will significantly reduce the
  40 amount of work you will have to do in the unix environment.
  41
  42 The MySQL 3.23.46 binary installation works well with Mac OS X 10.1
  43 and PhpWiki. After you install and test mySQL follow the instructions
  44 given in INSTALL.mysql to prepare a new database for use with PhpWiki.
  45
  46
  47 Apache PHP Module
  48 -----------------
  49 The default PHP module for Apache as supplied by Apple does work with
  50 PhpWiki but is missing support for the zlib and GD libraries. Wiki
  51 will still produce a valid ZIP file when an administrator saves a ZIP
  52 dump of the database but it will not use any compression.
  53
  54 If you want compressed ZIP dumps you will have to install a version of
  55 PHP which does support the zlib library, or compile PHP yourself and
  56 replace the default /usr/libexec/httpd/libphp4.so (part of the
  57 Apple-supplied Apache installation).
  58
  59 PHP with GD library support is required to use "text2png", an
  60 experimental plugin for Wiki 1.3.
  61
  62 PhpWiki 1.3 already knows where to find the required PEAR.php on Mac
  63 OS X systems. However if you need to use PEAR with other PHP
  64 applications, edit or create the file /usr/local/lib/php.ini then add
  65 the following line:
  66
  67 include_path = ".:/System/Library/PHP";
  68
  69 If you compiled a version of PHP yourself (perhaps newer than the
  70 4.0.6 version included by Apple) the path will already be included in
  71 the php.ini file. In that case you shouldn't have to change the path,
  72 unless you installed PHP into a location other than the default
  73 /usr/local/ prefix.
  74
  75
  76 Obtaining and Installing mySQL and libphp4.so
  77 ---------------------------------------------
  78 Mark Liyanage has graciously provided precompiled Mac OS X versions of
  79 mySQL, an updated PHP module for Apache and some installation
  80 instructions on his web site. He has also written some tips if you
  81 want to compile these programs for yourself.
  82
  83     <http://www.entropy.ch/software/macosx/>
  84
  85 Note that whether you use the built-in PHP module or another PHP
  86 module, it must be activated in Apache's httpd.conf before you can use
  87 PHP. Take a look at Mark's PHP installation instructions or read the
  88 Apache documentation for more information.
  89
  90 A good place to find other distributions of mySQL or PostgreSQL which
  91 can be used with Mac OS X are listed at:
  92
  93     <http://versiontracker.com/macosx/>
  94
  95
  96 PHP 4.1 and Mac OS X
  97 --------------------
  98 The version of PHP 4.1 from Mark Liyanage's web site requires an
  99 updated PEAR library. PhpWiki seems to work anyway but it will produce
 100 warnings about a depreciated user function with each page load. Move
 101 the current contents of '/System/Library/PHP' into a backup folder,
 102 such as '/System/Library/PHP/PEAR-4.0.6'. Take the contents of the
 103 'pear' folder from the official PHP 4.1 tarball (php-4.1.0.tar.gz) and
 104 move it into '/System/Library/PHP'. A precompiled PHP 4.1 module for
 105 Apache and the PearDB support files are also available at:
 106
 107     <http://homepage.mac.com/carstenklapp/>
 108
 109
 110 PhpWiki Configuration Notes
 111 ---------------------------
 112 Move the phpwiki folder into the directory used by the web server. In
 113 Mac OS X 10.1 this folder will be "/Library/WebServer/Documents"
 114 (unless you previously changed it to somewhere else in the
 115 configuration file "/private/etc/httpd/httpd.conf").
 116
 117 Follow the generalized installation instructions described in INSTALL
 118 but with the changes below.
 119
 120
 121 1. The Mac OS X Apache web server runs as user "www" and this works
 122    fine with PhpWiki so long as "Everyone" has at least read-only
 123    access in the phpwiki folder's Get Info.
 124
 125 If you want to perform serial dumps instead of ZIP dumps you need to
 126 set at least one directory to be accessible read-write by the http
 127 server. The easiest solution is probably to create a new folder called
 128 "dumps" inside the phpwiki folder, then give the user "www" read-write
 129 access to it in the terminal:
 130
 131 sudo chown www:www /System/Library/phpwiki/dumps
 132 sudo chmod u+wrx /System/Library/phpwiki/dumps
 133
 134 2. A few lines need to be inserted into Apache's configuration in
 135    order to use "nice" URLs with PhpWiki such as:
 136
 137     http://somehost/wiki?GoodStyle
 138
 139 Open the terminal and type in the following to edit the web server
 140 configuration file (enter your administration password when prompted):
 141
 142 sudo pico /etc/httpd/httpd.conf
 143
 144 Scroll down to the <IfModule mod-alias.c> section. Copy the comment
 145 line "#PhpWiki 1.3 aliases" and the four lines below it, then paste it
 146 into the mod_alias section as shown below.
 147
 148 <IfModule mod_alias.c>
 149
 150     #
 151     # Note that if you include a trailing / on fakename then the server will
 152     # require it to be present in the URL.  So "/icons" isn't aliased in this
 153     # example, only "/icons/".  If the fakename is slash-terminated, then the
 154     # realname must also be slash terminated, and if the fakename omits the
 155     # trailing slash, the realname must also omit it.
 156     #
 157     Alias /icons/ "/usr/share/httpd/icons/"
 158
 159 #PhpWiki 1.3 aliases
 160     Alias /wiki/images/ "/Library/WebServer/Documents/phpwiki/images/"
 161     Alias /wiki/images "/Library/WebServer/Documents/phpwiki/images"
 162     Alias /wiki/ "/Library/WebServer/Documents/phpwiki/index.php/"
 163     Alias /wiki "/Library/WebServer/Documents/phpwiki/index.php"
 164
 165
 166 To save your changes and exit, press 'control-x', then 'y' followed by
 167 the 'return' key.
 168
 169 Restart the Web Sharing server from the System Preferences "Sharing"
 170 control panel or from the terminal:
 171
 172 sudo apachectl graceful
 173
 174 Next, edit the following lines in part five of index.php to match
 175 the following:
 176
 177 define('DATA_PATH', '/wiki');
 178 define('USE_PATH_INFO', true);
 179 define('VIRTUAL_PATH', '/wiki');
 180
 181 3. To retain your PhpWiki logs between system restarts you should
 182    specify a non-temporary directory. I recommend you use the same
 183    folder where the web-server stores it's logs. Change the following
 184    (line 73) in index.php from:
 185
 186 define('ACCESS_LOG', '/tmp/wiki_access_log');
 187
 188 to something like:
 189
 190 define('ACCESS_LOG', '/private/var/log/httpd/wiki_access.log');
 191
 192 Note that the automatic /etc/daily and weekly cron cleanup routines
 193 will not touch the Wiki log file--even if it is in the same directory
 194 as the httpd logs--it will be up to you to Trash it once in a while or
 195 write your own /etc/daily.local file to include it as part of a server
 196 log rotation.
 197
 198
 199 Using Apple's Project Builder with PhpWiki
 200 ------------------------------------------
 201 A PB project file is available on the SourceForge CVS server to allow
 202 you to easily edit PhpWiki's source code using Apple's Project
 203 Builder. If you have not yet updated to PB 1.1.1 (Dec 2001 DevTools)
 204 it is highly recommended you do so because the PhpWiki source are
 205 written in ISO-8859-1, and some of the bug fixes are pertinent to file
 206 encoding.
 207
 208 PB has some bugs which makes it impossible (in PB 1.1) or difficult
 209 (in PB 1.1.1) to select the correct character encoding in the GUI for
 210 any pre-existing source code files. By using this project file you
 211 will find the PhpWiki source files are already preset to use the
 212 correct ISO-8859-1 (Western Latin-1) encoding.
 213
 214 The Build target settings have also been preconfigured to
 215 automatically build a "legacy Makefile", by invoking
 216 '/usr/bin/gnumake' in the folder'./phpwiki/locale'. When you update
 217 and save one of the language translation files found in
 218 './phpwiki/locale/po/', you can simply click the build button in the
 219 toolbar to run make, which in turn calls another script and xgettext.
 220
 221 To download the phpwiki.pbxproj bundle, use CVS to checkout the module
 222 named "phpwiki.pbxproj" then place it into the same folder which
 223 contains your "phpwiki" folder.
 224
 225 Note that as of this writing (PB 1.1.1), you can only use Project
 226 Builder's CVS facilities in Anonymous mode with the SourceForge CVS
 227 server. (Technical explanation: PB tries to use rsh instead of ssh as
 228 is required for SourceForge).
 229
 230 Emacs Users: You can add custom Alt-key bindings to Project Builder
 231 for some common Emacs stuff:  *Note the wrapped url!
 232 http://developer.apple.com/techpubs/macosx/Cocoa/TasksAndConcepts/
 233 ProgrammingTopics/TextDisplay/Tasks/TextDefaultsAndBindings.html
 234
 235
 236 If you have problems after all of this, try contacting the
 237 phpwiki-talk list at phpwiki-talk@lists.sourceforge.net.
 238
 239 Carsten Klapp
 240 carstenklapp@mac.com
 241
 242 $Id: INSTALL.MacOSX,v 1.9 2001-12-30 23:38:34 carstenklapp Exp $