Jump to content

Setup a ProcessWire environment on a fresh MacOS X install

Martijn Geerts

Recommended Posts

Recently I got a brand new iMac so I needed to install PHP SQL and configure Apache. I'm using the same web develop environment for years and I'm really happy with it. Raymond is also using this and Arjen did the same recently. I love to share how I setup this environment in a step by step tutorial. Let's setup PHP, MYSQL and activate mail using gmail smtp for OSX 10.6 and up, perfectly suitable for ProcessWire. It doesn't install Apache, it uses the Apache installation, which comes with OS X.

The PHP installer package is created by Liip and it is based on entropy's php package. For MYSQL we gonna install the DMG Archive (x86, 64-bit). After we installed PHP, we configure Apache & PHP so that we’re able to run the ProcessWire sites in our own ~/Sites directory.

For El Capitan see Arjen's https://processwire.com/talk/topic/5797-setup-a-processwire-environment-on-a-fresh-macos-x-install/?p=103674 

Install PHP

We gonna use the PHP installer created by Liip. (more information)

  • Go to: /Applications/Utilities/

  • Open: Terminal.app

  • Type: 

    curl -s http://php-osx.liip.ch/install.sh | bash -s 5.5
  • Press: RETURN

  • Type: your admin password

  • Press: RETURN ( download starts and continues with a the install )

note: If you want to have an older PHP version, replace 5.5 with 5.4.  (PHP 5.5 is the current stable)

After the install is completed Apache is restarted and complains about “Could not reliably determine the server's fully qualified domain name, using your-computer-name.local for ServerName”. This notice is not a problem, we only use this Mac for local website development.

Setup Apache

  • Open a new finder window.

  • Press: shift + command + g ( Go to folder )

  • Type: /etc/apache2/

  • Press: go

  • Open: httpd.conf

  • Find the line: #Include /private/etc/apache2/extra/httpd-vhosts.conf

  • Remove the # infront to enable.

  • Press save and enter your password when asked.

Enable the use of ~/Sites folder:
  • Open the folder /etc/apache2/users/
  • * Duplicate the Guest.conf and name it martijn.conf 
  • Open the duplicated file that we created
  • * Change: <Directory "/Users/Guest/Sites/"> to <Directory "/Users/martijn/Sites/">
  • Change: AllowOverride None, to AllowOverride All

  • Save the file. 

The file should look like:
<Directory "/Users/martijn/Sites/">
    Options Indexes MultiViews
    AllowOverride All
    Order allow,deny
    Allow from all

Configure the vhosts includes

  • Open /etc/apache2/extra/httpd-vhosts.conf
  • Comment out the 2 VirtualHost examples by putting a # in front
  • Be sure that NameVirtualHost *:80 doesn’t start with a # sign.
  • Add the include: include /Users/martijn/Sites/_vHosts/*.conf at the bottom of the file.
  • Save the file, password will be asked.
The file should at least have these two lines:
NameVirtualHost *:80
include /Users/martijn/Sites/_vHosts/*.conf
( Replace martijn with your short admin name )

The ~/Sites folder  (Users/martijn/Sites)

  • Goto your user Home folder.
  • Create the Sites folder in your user home ( if not exist )
  • Create inside the Sites folder a folder called _vHosts
  • Create the folder domains inside the ~/Sites folder
  • Create a folder inside the domains folder called processwire ( processwire will be the domain name )
  • Inside the processwire folder create 2 directories:
  • 1.    htdocs
  • 2.    logs ( make this writeable by right click the folder and choose Get info )
  • Create inside the htdocs folder a file called index.html with some content.
The folder structure should look like: 
  |`-- _vHosts
   `-- domains
       `-- processwire
           |-- htdocs
           |   `-- index.html
           `-- logs       

Configure PHP

  • Open the file: /usr/local/php5/php.d/99-liip-developer.ini  ( This file is the last ini file that gets loaded, so perfectly suitable for your personal settings )

  • Make your personal changes here. ( setting xdebug.max_nesting_level=1000 for example if needed )

  • Save the file ( password will be asked. )

  • Make an alias the this file by right click and choose: Make Alias

  • Name the alias _settings.ini or what ever you want to name it.

  • Move the alias to your ~/Sites folder

Create a vHost

In our ~/Sites folder we created a folder named _vHosts. This folder we gonna use for the vHosts. All files ending with .conf in this folder will be loaded when we (re-)start Apache.

  • Create a new file with your favourite text editor.
  • Type the following in the file: ( Replace martijn with your short admin name )
<VirtualHost *:80>
    DocumentRoot /Users/martijn/Sites/domains/processwire/htdocs/
    ServerName processwire 
    ErrorLog /Users/martijn/Sites/domains/processwire/logs/error.log.txt
    CustomLog /Users/martijn/Sites/domains/processwire/logs/access.log.txt common
  • Save the file with the filename processwire.conf in the folder _vHosts

The hosts file
  • Go to the Finder
  • Press: shift + command + g  ( Go to folder )

  • Type: /etc/hosts & press return

  • Open the hosts file with you favourite editor

  • Type processwire below    localhost but above    broadcasthost

  • Save the file

  • Right click the file & choose: Make Alias

  • Move the alias that you created to your ~/Sites folder

  • Rename it to _hosts

The file should look like:
# Host Database
# localhost is used to configure the loopback interface
# when the system is booting.  Do not change this entry.
##	localhost	processwire	broadcasthost
::1             localhost 
fe80::1%lo0	localhost

Test the Apache & PHP setup

  • Go to: /Applications/Utilities/

  • Open: Terminal.app

  • Type: 

    sudo apachectl restart
  • Press: RETURN

  • Type: your admin password

  • Press: RETURN

At this point Apache & PHP will be up and running.

Go to a browser and type: processwire/ in the address bar and press enter.


For managing MySQL databases I use Sequel Pro it's a very handy tool and in this tutorial we set the root user password with it. For the SQL server we gonna use the MySQL DMG Archive (x86, 64-bit) 

Download the following:

  • Open the mysql-5.6.16-osx10.7-x86_64 image
  • install mysql-5.6.16-osx10.7-x86_64.pkg, MySQLStartupItem.pkg & install the prefPane

if MACOSX complains about: mysql-5.6.16-osx10.7-x86_64.pkg” can’t be opened because it is from an unidentified developer. ) 

  You should open your System Preferences, go to Security & Privacy and Allow apps downloaded from: Anywhere

Set the root user password
  • Double click the sequel-pro-1.0.2.dmg.
  • The disc image will mount
  • Drag'n'drop the Sequel Pro.app to your /Applications/ folder.
  • Open Sequel Pro
  • Type by name:

  • Type by host:

  • Type by username: root

  • Login

  • Press command + u 

  • Select the root user on the left side

  • Fill in the password

  • Press apply

We're Done


Todo how to use it after the setup is complete

Edited by Martijn Geerts
  • Like 21
Link to comment
Share on other sites

.....Just one question: 

What's the benefit of install everything manually vs a quick and easy MAMP installation?

One...you can easily upgrade your software version (e.g. PHP) without waiting for MAMP to upgrade...But am lazy...so I still use XAMPP  O0

Martjin. Thanks for this write-up! Very helpful not only for MAC users, but the ideas are applicable to other environments too.

Edited by kongondo
  • Like 4
Link to comment
Share on other sites

Don't know if there's a real benefit for this in-comparison with MAMP (no experience with MAMP). I started this setup before MAMP was there and it works without problems. It works with the default Apple shipped Apache & in the past you could turn on/off apache in your System Preferences. I do like the fact that I don't need an extra GUI app to put the environment on and off. Every time I start the machine Apache PHP & SQL is loaded, no questions asked.  I especially like the ~/Sites setup. I can see the logs from the website working on directly in the same folder. There's room enough to store information needed next to the site when building. And It's all In your user home folder.

  • Like 3
Link to comment
Share on other sites

 Martjin. Thanks for this write-up! Very helpful not only for MAC users, but the ideas are applicable to other environments too.

Yep, that sounds exactly like what I have done the last 10+ years on my local win machines (w2k, xp , win7), except that there isn't allready an Apache installed.

  • Like 1
Link to comment
Share on other sites

Thanks Martijn - works great on my Mac Mini!

I am not on a fixed IP, so I wonder what's the best way to share a local dev site with a client?

I found https://forwardhq.com/ (paid service), but can' get it running on my mac (seems like it doesn't support Ruby versions above 1.9.3...)

How du you guys solve this? DynDNS or similar? Any feedback on this is welcome.


  • Like 1
Link to comment
Share on other sites

  • 2 months later...

Great tutorial Martijn, thanks.

I also recently reinstalled my mac and I started to go through all this hassle of installing all components manually. Someone on twitter pointed me to homebrew, which I had heard of but had not used until then (http://brew.sh/). It's a packet manager, I am sure most of you mac users have heard of it.

It makes installing these components and their dependencies almost headache-free, and they are easily updatable.

Still, the configuration can be a pain in the butt, so your tips are very valuable.

At the moment I am eyeballing with Vagrant but haven't had the time yet to grasp the whole beast to make it fit my needs.

  • Like 1
Link to comment
Share on other sites

  • 2 months later...

Great topic, thanks for this! Finally managed to get my PW running :)

I did make one mistake though, and that was that I forgot to create the htdocs and logs folders, so my apache wouldn't start again after restarting.

After using the following code, I found out that the folders were the problem:

sudo apachectl configtest

Thanks to Martijn I found this out. Thanks again :)

  • Like 2
Link to comment
Share on other sites

  • 2 weeks later...

So, I'm just trying to gain some experience by making a second installation on my local mac...

If I'm correct, I would have to add the new data into these places:

Folder name: mdbnl

Desired address in my browser: mdbnl/

  |`-- _vHosts
   `-- domains
       `-- mdbnl
           |-- htdocs
           |   `-- index.html
           `-- logs       

Vhosts (_vHosts/mdbnl.conf):

<VirtualHost *:80>
    DocumentRoot /Users/marinusdebeer/Sites/domains/mdbnl/htdocs/
    ServerName mdbnl 
    ErrorLog /Users/marinusdebeer/Sites/domains/mdbnl/logs/error.log.txt
    CustomLog /Users/marinusdebeer/Sites/domains/mdbnl/logs/access.log.txt common

In the hosts file I should add:	localhost	processwire	mdbnl

And after all that just restart apache, put processwire in the right folder and setup from there in it's unique database.

Is this all good? Or am I missing a step? :)


Actually, I tried this, and it seems to work fine, so I guess this is the way to do it :)

I'll leave this up here for anyone who wants to make a second install of processwire on their local Mac environment.

  • Like 1
Link to comment
Share on other sites

  • 10 months later...
  • 2 months later...

I just installed El Capitan and once again when you upgrade Mac OSX the system creates a brand new /etc/apache2/httpd.conf file. You'll want to make some changes. Here are some quick fixes to make this set-up work again:

  1. First backup the new httpd.conf in case something goes wrong.
  2. Diff the new httpd.conf with your old httpd.conf.pre-update file.
  3. Apply the changes in the new httpd.conf file.
  4. Restart Apache and you good to go.

I had to change:

  1. Enable rewrite_module on line 168
  2. Enable php5_module on line 169
  3. Change User and Group to my own to avoid messy permissions stuff on lines 181-182
  4. Enable Virtual hosts on line 499

I used to mess for hours with this stuff. Nowadays it's pretty straight forward and I got it up-and-running in under 5 minutes.

  • Like 2
Link to comment
Share on other sites

Nice tutorial for noobs!! I will adapt the "~/Sites" part of the tutorial, the part where you include the other vhosts file and the error logs, god was I tired of looking for the apache /extra/http-vhosts.conf inside the MAMP mumbo jumbo path, I recently saved a bookmark in my text editor to just have it at hand.

Link to comment
Share on other sites

  • 1 year later...

Hi all,

I'm new to Processwire, I just wanted to say thanks Martijn for this step by step guide.

I would highly recommend this to any Mac user getting started with Processwire.

I also followed these steps for using Gmail as the mail server.

I would say the benefits of following a manual install (for a noob in terms running a local server) are high.

I've now learned HOW the configuration works, and where the settings are stored, rather than running an install process.

Thanks again!




  • Like 2
Link to comment
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

  • Recently Browsing   0 members

    • No registered users viewing this page.
  • Create New...