Mac OS X / nginx / MariaDB / PHP / Aegir (MEMPÆ)

drupal planet, drupal, os x, aegir, nginx, mariadb, php

We have an updated post on setting up Aegir on OSX (with Drush 5 and tested with Mountain Lion)

At Realityloop we've found Ægir to be a major time saver and great tool for deplying Drupal websites, so several months ago we started on the path to get Aegir running locally on our Mac's for development purposes, with one caveat.. using NGINX instead of Apache!

Without further ado here is how to do it both by Video and Text instructions, please follow the instructions carefully as this process has been refined to make the process as painless as possible. Yes, this works on both Lion and Snow Leopard.

Step 1: Install the requirements for this process; Xcode and Homebrew

XCode is required for Homebrew to compile nginx, mariadb and php.

  • Download and install Xcode using the Mac App Store with the link above
    (it's free, but will take a while to download if your Internet connection is slow)
  • Once the download has finished run the newly downloaded ‘Install Xcode’ app which will appear in Launchpad and follow the prompts.
  • Now go back to your terminal window and type the following to install Homebrew
    1. $ ruby -e "$(curl -fsSL"
  • Download homebrew-alt so we can rebuild php with the required components
    1. $ brew tap homebrew/dupes
    2. $ brew tap josegonzalez/homebrew-php
  • Add /usr/local/sbin to you path
    1. $ nano ~/.bash_profile
  • Paste the following into editor then Ctrl+X and Y to save
    1. PATH=$PATH:/usr/local/sbin; export PATH
Step 2: Setting up bind

BIND or named is the most widely used DNS software on the Internet, we will be configuring this for wildcard DNS of our development TLD (Top Level Domain) and using Google DNS as secondary DNS lookup for all other requests.

Open the terminal application and enter the following:

  • become root
    1. $ sudo -i
  • Backup the default configuration
    1. $ cp /etc/named.conf /etc/named.conf.bck
  • Create the keyfile that is read by both rndc and named on startup
    1. $ rndc-confgen -a
  • Edit the named.conf file
    1. $ nano /etc/named.conf
  • Inside the “options {“ block add the following before the last }
    1. forwarders {
    2.; //Google DNS
    3.; //Google DNS
    4. };
  • Add the following just before zone "" IN {
    1. zone "ld" IN {
    2. type master;
    3. file "db.ld";
    4. };
  • Save your changes by hitting Ctrl+X then Y
  • Create db.ld file, we chose .ld for our TLD as it equated to local development in our minds
    1. $ nano /var/named/db.ld
  • Paste the following
    1. ld. 7200 IN SOA dev. root.ld. (
    2. 2008031801 ; Serial
    3. 15 ; Refresh every 15 minutes
    4. 3600 ; Retry every hour
    5. 3000000 ; Expire after a month+
    6. 86400 ) ; Minimum ttl of 1 day
    7. IN NS ld.
    8. IN MX 10 ld.
    10. IN A
    11. *.ld. IN A
  • Save your changes by hitting Ctrl+X then Y
  • Run the following commands to ensure configuration is ok
    1. $ named-checkconf /etc/named.conf
    2. $ named-checkzone ld /var/named/db.ld
  • Set your computers network settings to use as DNS server in System Preferences -> Network for both Wireless and Ethernet connections by clicking Advanced and selecting the DNS tab
  • Set Bind to load on startup, and load it right now
    1. $ launchctl load -w /System/Library/LaunchDaemons/org.isc.named.plist
  • Check setup with dig, were looking for NOERROR in the returned text
    1. $ dig test.ld
  • We can also test ping which should return something like the following (if not try a restart or dscacheutil -flushcache), hit Ctrl+C to cancel ping task
    1. $ ping test.ld
    2. PING test.ld ( 56 data bytes
    3. 64 bytes from icmp_seq=0 ttl=64 time=0.033 ms
    4. 64 bytes from icmp_seq=1 ttl=64 time=0.061 ms
    5. 64 bytes from icmp_seq=2 ttl=64 time=0.060 ms
  • Set hostname as it's required for sane default in aegir setup, we chose rl.ld for Realityloop Local Development you can use something else instead of rl but it needs to end in .ld
    1. $ scutil --set HostName rl.ld
  • Create configuration so that the wilcard is still accesible when you are not connected to a network
    1. mkdir /etc/resolver
    2. nano /etc/resolver/ld
    Paste the following and save using CTRL+X then Y to save:
    1. nameserver
  • Revert back to your default user instead of root
    1. $ exit
Step 3: Install nginx

nginx (pronounced “engine-x”) is a Web server and a reverse proxy server for HTTP, SMTP, POP3 and IMAP protocols, with a strong focus on high concurrency, performance and low memory usage.

  • Unless this is a fresh install of OS X you need to ensure Apache doesn't load on startup
    1. $ sudo launchctl unload -w /System/Library/LaunchDaemons/org.apache.httpd.plist
  • Optional: Edit nginx.rb homebrew installer to add --with-debug flag
    1. $ sudo nano /usr/local/Library/Formula/nginx.rb
  • Add the following line in the args = ["--prefix=#{prefix}", section after "--with-pcre", followed by Ctrl+X then Y to save.
    1. "--with-debug",
  • Still in the ‘Terminal app’, type the following command
    1. $ brew install nginx
  • Once nginx is compiled, backup the default nginx config
    1. $ mv /usr/local/etc/nginx/nginx.conf /usr/local/etc/nginx/nginx.conf.bak
  • Download our config as follows
    1. $ curl > /usr/local/etc/nginx/nginx.conf
  • Edit the config to set your username, replace [username] on the third line with your own username, hit Ctrl+X and Y to save
    1. $ nano /usr/local/etc/nginx/nginx.conf
  • Make nginx log files visible in Console app
    1. $ sudo mkdir /var/log/nginx
  • Create the following directorty to stop “"/var/lib/nginx/speed" failed (2: No such file or directory)” error
    1. $ sudo mkdir /var/lib/nginx
Step 4: MariaDB

MariaDB is a community-developed branch of the MySQL database, the impetus being the community maintenance of its free status under GPL, as opposed to any uncertainty of MySQL license status under its current ownership by Oracle.

The intent also being to maintain high fidelity with MySQL, ensuring a "drop-in" replacement capability with library binary equivalency and exacting matching with MySQL APIs and commands. It includes the XtraDB storage engine as a replacement for InnoDB.

  • Still in the ‘Terminal app’, type the following command
    1. $ brew install mariadb
  • Once compilation has finished unset TMPDIR
    1. unset TMPDIR
  • Then mysql_install_db
    1. $ mysql_install_db
  • but don't follow any more of the prompts just now or you will run into problems, we'll do the rest later.
Step 5: Update php
  • Backup your original version of PHP, in the case you ever want to revert to a vanilla state. Note: You may need to repeat this step anytime you use combo updater to install OS X updates
    1. $ sudo mv /usr/bin/php /usr/bin/php-apple
  • Execute the brew install process using hombrew-alt php brew file
    1. $ brew install php53 --with-mysql --with-fpm
  • Once compilation is complete create your php-fpm config file
    1. $ cp /usr/local/Cellar/php/5.3.8/etc/php-fpm.conf.default /usr/local/Cellar/php/5.3.8/etc/php-fpm.conf
  • Create symbolic link for it in /usr/local/etc/
    1. $ sudo ln -s /usr/local/Cellar/php/5.3.8/etc/php-fpm.conf /usr/local/etc/php-fpm.conf
  • Edit the conf file
    1. $ nano /usr/local/etc/php-fpm.conf
  • Add the following line below ;pid = run/
    1. pid = /usr/local/var/run/
  • Update the user and group section as follows
    1. user = _www
    2. group = _www
  • Remove the ; from the start of the following lines then save using Ctrl+X then Y
    1. pm.start_servers = 3
    2. pm.min_spare_servers = 3
    3. pm.max_spare_servers = 5
    4. pm.max_requests = 500
  • Create directory and file for php-fpm log
    1. $ mkdir /usr/local/Cellar/php/5.3.8/var/log/
    2. $ touch /usr/local/Cellar/php/5.3.8/var/log/php-fpm.log
  • Make our log file visible in Console app
    1. $ sudo ln -s /usr/local/Cellar/php/5.3.8/var/log/php-fpm.log /var/log/nginx/php-fpm.log
  • Set your timezone in php.ini
    1. $ nano /usr/local/etc/php.ini
  • I added the follwing under the ;date.timezone = line
    1. date.timezone = Australia/Melbourne
  • And updated the Memory limit as follows, then saved with Ctrl+X then Y
    1. memory_limit = 256M
Step 6: Service Launch Daemons

This is so everything runs automatically on startup

  • Type the following into you open Terminal window
    1. $ sudo -i
  • Download the LaunchDaemon to load nginx on boot
    1. $ curl > /System/Library/LaunchDaemons/org.homebrew.nginx.plist
  • Download LaunchDaemon for php-fpm
    1. $ curl > /System/Library/LaunchDaemons/org.homebrew.php-fpm.plist
  • Copy the LaunchDaemon to load mariadb on boot into place
    1. $ cp /usr/local/Cellar/mariadb/5.2.8/com.mysql.mysqld.plist /System/Library/LaunchDaemons/com.mysql.mysqld.plist
  • Restart your computer to enable the services Yes you really need to do this now, or the next step will not work
  • Open terminal again and type the following
    1. $ sudo /usr/local/Cellar/mariadb/5.2.8/bin/mysql_secure_installation
  • Answer the prompts as follows, replace [password] with a password of your own chosing
    1. Enter current password for root (enter for none): [Enter]
    2. Set root password? [Y/n] y
    3. New password: [password]
    4. Re-enter new password: [password]
    5. Remove anonymous users? [Y/n] y
    6. Disallow root login remotely? [Y/n] y
    7. Remove test database and access to it? [Y/n] y
    8. Reload privilege tables now? [Y/n] y
Step 7: Drush and Aegir

Your in the home stretch now!

  • Make a few small changes required for this to work properly
    1. $ sudo mkdir /var/aegir
    2. $ sudo chown `whoami` /var/aegir
    3. $ sudo chgrp staff /var/aegir
    4. $ sudo dscl . append /Groups/_www GroupMembership `whoami`
  • Allow your user to restart nginx, be sure to replace [username] with your own username.
    1. $ sudo -i
    2. $ echo "[username] ALL=NOPASSWD: /usr/local/sbin/nginx" >> /etc/sudoers
    3. $ exit
  • Manually Install Drush and Aegir components
    1. $ export DRUSH_VERSION=7.x-4.5
    2. $ curl -O$DRUSH_VERSION.tar.gz
    3. $ gunzip -c drush-$DRUSH_VERSION.tar.gz | tar -xf -
    4. $ rm drush-$DRUSH_VERSION.tar.gz
  • Make Drush accesible via your path
    1. $ sudo ln -s ~/drush/drush /usr/local/bin/drush
  • Download drush_make and provision
    1. $ drush dl drush_make-6.x --destination="/users/`whoami`/.drush"
    2. $ drush dl provision-6.x --destination="/users/`whoami`/.drush"
  • Apply the following patch to provision until it's part of aegir core
  • Create symbolic link for aegir vhosts
    1. $ sudo ln -s /var/aegir/config/nginx.conf /usr/local/etc/nginx/aegir.conf
  • Install Hostmaster!
    1. $ drush hostmaster-install --aegir_root='/var/aegir' --root='/var/aegir/hostmaster-6.x-1.4' --http_service_type=nginx
  • Remove the default platforms dir and create a symlink for so you can put your Platforms in ~/Sites/ directory
    1. $ mkdir /Users/`whoami`/Sites
    2. $ rmdir /var/aegir/platforms
    3. $ ln -s /Users/`whoami`/Sites /var/aegir/platforms
  • Open your web browser and start creating platforms and sites!

It's been a great learning process, we've met some great people along the way, and it allowed us to commit code back to the Aegir project to make it easier for everyone moving forward.

Special thanks to Steven Jones (darthsteven) for his assistance during DrupalCon London, Grace (omega8cc) for her assistance with patch for getting aegir to restart nginx under OS X, António Almeida (perusio) for assistance with nginx during the DrupalCon London Sprint day, and the whole Aegir development team for such a great tool. Also thanks to Dave Hall (skwashd) who let us know some improvements to *nix command line commands we were using.



I used to maintain a PHP 5.2 brew and I used it with someone else's 5.3 brew for Drupal dev. You shouldn't need to mv the built in php from apple. The homebrew way is to only use /usr/local and maybe just preference /usr/local/bin in PATH to make your custom builds the default.

Great post!

Submitted by Boris Gordon on October 26, 2011 - 12:47am

It would be great if somoene can confirm this on a clean setup, then we can update the documentation.

Submitted by Brian Gilbert on October 26, 2011 - 6:24am

How different is it for Ubuntu intallation? Will this tutorial help with ubuntu 10.04? Thanks

Submitted by Vik on October 26, 2011 - 2:21am
Submitted by Brian Gilbert on October 26, 2011 - 8:45am

I would be curious to know if you've found many issues with deploying sites developed using this setup on production machines with different setup (like traditional lamp)

Submitted by Ryan Cross on October 26, 2011 - 3:48am

Hi Ryan,
No issues so far other than the usual ones you would find with moving an aegir site to a non-aegir environment.

If you set the primary domain correctly you shouldn't face any issues. What we would really like to see is hostmaster to hostmaster migrations, and we have voiced this request with Steven Jones as it would make things pretty much seamless.

Submitted by Brian Gilbert on October 26, 2011 - 6:22am


I've come across a few minor issues with a few modules, which is actually a good thing as they where issues with modules under Nginx that I may not have known about otherwise and have fixed those that I can.

As for standard development, no issues, other than trying to figure out what to do with all my free time now that everything is so quick and easy :)

Submitted by Stuart Clark on October 26, 2011 - 8:58am

Nice video. I have a few suggestions on how to improve things.

The <a href="">Google DNS</a> IP addresses are and <strong></strong> not <strong></strong>.

In my experience <a href="">dnsmasq</a> is a better and more lightweight DNS solution for dev environments over BIND.

Your PHP FPM config seems to massively overspeced for a local dev environment. I'd recommend the following settings:
pm.start_servers = 3
pm.min_spare_servers = 3
pm.max_spare_servers = 5
pm.max_requests = 500

This config means you don't have idle threads sitting around consuming memory. Given that you up the memory limit to 256M, your dev environment could consume upto 8.75G of RAM (35*256M). The above defaults are saner for most devs.

"sudo -i" is preferred over "sudo -s" for becoming root.

visudo is the preferred method for editing the /etc/sudoers file under Linux. I don't know if OSX support this, but if it does you should use it as it stops you creating an invalid config file.

Where using your own username "`whoami`" (without the quotes) can be used to input the current user's name. for example 'drush dl drush-make-6.x --destination="users/`whoami`/.drush"'

You can use [CTRL]-L should clear your terminal, instead of typing "clear" all the time

<strong>Note:</strong> I emailed this to Brian last night because Mollom was misbehaving.

Submitted by Dave Hall on October 26, 2011 - 5:06pm

Hi Dave,
We mainly chose to use bind as it comes with OS X by default. If we get some time we may investigate dnsmasq though, thanks.

Thanks for the CTRL+L shortcut.. I'll make use of that a lot in the future.

Will do some testing and probably update PHP FPM settings soon.

Submitted by Brian Gilbert on October 26, 2011 - 5:13pm

Why aren't you installing drush from homebrew? And did you know you can install drush_make by the following drush command: drush dl drush_make
This will download drush_make and install it in the right directory.

Submitted by Nicolas on October 31, 2011 - 3:05am

Damn, I'm stuck. Aegir 1.5 is out, but that patch was not applied... So I ran through the hostmaster process, but with some warnings (about reloading nginx). I restarted my mac, but aegir.ld is not working. When checking mysql, there is an aegirld database.
When trying to run that postmaster command again, I run into a mysql error.
How can I analyze what's wrong? Something wrong with the DNS? Where is aegir.ld set?
ping & dig aegir.ld are working... When opening aegis.ld I get this in the url: file:///Applications/ With the message the server can't be found. Is there a way to check if nginx is working?


Submitted by Nicolas on November 9, 2011 - 6:48am

Ok, did some more research. I still had an error in my php-fpm conf. I corrected it. Now everything is up. But aegir.ld is not working. Is the hostmaster command supposed to add a vhost to nginx? Because it is not there.
How can I clean out all the hostmaster stuff and start that command over again? Or could you tell me where the aegir.ld vhost is. In which conf file? And what should be in there?

Submitted by Nicolas on November 9, 2011 - 7:37am

Hi Nicolas,
to clear hostmaster and start again delete the db that was created and
you should see a vhost that will need to be removed at
as well

Submitted by Brian Gilbert on November 9, 2011 - 9:07am

I've gone through all of this on a Lion system that was upgraded from Snow Leopard and is up to date with Apple software updates.

Having similar troubles to Nicolas where the first time I tried to install hostmaster there were errors saying that nginx couldn't be restarted - I had to put my username *and* a group name into the nginx.conf file (I haven't set up nginx manually before so i didn't realize that was necessary in Step 3) to get nginx to stop complaining when I restart it.

Anyway, I cleared out aegir/hostmaster files as suggested here and re-installed it. So I'm at the end of the process after having gone through each step with no more warnings or errors, I can ping test.ld and dig test.ld says NOERROR.

I can see that there are running master/worker processes for nginx and for php-fpm, i can connect to and see the aegirld database tables.

This all looks good to me, except that when I actually try to visit aegir.ld in any browser (FF/chrome/safari) I get "Unable to connect, Firefox can't establish a connection to the server".

I'm kind of out of ideas as to how I should go about debugging this any further, let alone fixing it, although I have a feeling (hope) that it is a config issue somewhere that should be easy enough to fix once it has been identified. I'm also not sure if what I'm experiencing is an issue with the DNS, the nginx server or something else entirely...

Brian, any ideas for further things that I could try to isolate the problem?

Submitted by David Meister on November 13, 2011 - 5:07pm

Stuart helped me get this working.

So, some hopefully helpful feedback on this process:

1. The nginx config file referenced in the article wasn't the right one (it has been updated now)
2. Many people will have macports installed, if you do the steps to clean out macports could be helpful to come before trying to install homebrew, or at least a warning that this should be done before starting - this worked for me
3. Not sure if it is related to #2, but I had to wipe (or rename) /usr/local before installing homebrew -
4. I had to change the order of the entries in /etc/paths so that usr/local/bin was at the top
5. Not really something that everyone will come across, but having an apostrophe in your root password for MariaDB will cause aegir to not be able to verify the server or build new sites - to fix this, change the password for the database then click "edit" on the unverified server and update the password record in aegir

Submitted by David Meister on November 14, 2011 - 4:56pm

oh, i'd also like to mention that the step where you try to disable Apache is supposed to return an error if you don't have Apache running, so in this case error = good.

Submitted by David Meister on November 14, 2011 - 4:57pm

Thanks a million guys. I just downloaded the nginx.conf again, opened my browser, went to http://aegir.ld and it is working!
Great. Now I can start playing with aegir :)

Submitted by Nicolas on November 18, 2011 - 8:51pm

Just before you jump into step 7, you should do yourself a favour and open up activity monitor to make sure that you can see processes running for nginx, mysqld and php-fpm. Unfortunately my experience is that you're unlikely to get 100% success just copying and pasting these instructions into terminal - there will be some amount of debugging required for each system.

If you've followed the steps here and you can see all three then you're probably good to go for the aegir installation, if you're missing one or more of those working processes then the installation will *definitely* fail - but possibly not before dumping a bunch of files on your system that will need to be rooted out manually before you can re-attempt the installation.

Submitted by David Meister on November 27, 2011 - 8:42pm

I installed everything to test out Aegir, but I would like to add vhosts to nginx to quickly install existing sites (without importing them in aegir), site-by-side with the aegir install. How to do this? I tried adding a vhost in the nginx.conf file, but it isn't working... Any advice?


Submitted by Nicolas on January 8, 2012 - 8:42am

Mostly converted (but not tested due to lack of internets on the plane) here:

Submitted by halcyonCorsair on January 16, 2012 - 11:02pm

I sat down to do some work today to find that for the first time I can only get to my local (.ld) sights when I have an internet connection? With wifi turned off / disconnected I cant access aegir or any local sites but as soon as I connect I can? I haven't made any changes to any settings... Any suggestions on where I should start?

Submitted by Corey on January 18, 2012 - 7:26am

Hi Corey,

This is the one issue that we've also not been able to resolve yet, it appears that OS X disabled DNS when there is no network available.

We'd definitely appreciate if anyone has the knowledge to help us get past this limitation.

Submitted by Brian Gilbert on February 18, 2012 - 3:27pm

Very frustrating indeed, and hours of searching hasn't led me to a viable solution. Bonjour would be so practical, but I turned it off for now because I'm often working without an internet connection.

Good old /etc/hosts is doing the trick... for now :-(

Great post nonetheless. Thanks!

Submitted by N on February 20, 2012 - 4:32am

I&#39;ve just found a resolution to this issue:

sudo mkdir /etc/resolver
sudo nano /etc/resolver/ld
Paste the following and save using CTRL+X then Y to save:
And then reboot your machine, from then on you will be able to access your wilcard when disconnected from any networking!

Submitted by Brian Gilbert on March 9, 2012 - 8:17am

I had tried this previously, but I must be doing something wrong.

Although I can dig/ping .ld urls with wifi off, safari keeps telling me "you are not connected to internet"

So frustrating.

Submitted by N on March 17, 2012 - 8:44am

It works using Firefox, but not Safari and Chrome!?

I don't know if anyone else observed this behavior, but this is how it is for me.

I thought, this can't be true. So I restarted my machine, opened Chrome, Safari and Firefox, opened mysite.ld, turned wifi off and refreshed all three. Only Firefox displayed the site without an internet connection. Of course, I did this about 50 times! I tried different variations and sometimes Firefox didn't display the page, but mostly it would. It boggles my mind.

Submitted by N on March 27, 2012 - 5:54am

Just (re)did this on a fresh install of osx lion

Thought it might be worth mentioning the following updates

### homebrew installation ###

(as shown on the homebrew git page)
/usr/bin/ruby -e "$(/usr/bin/curl -fksSL"
### Library ALT ###
Library Alt is no longer maintained by git user adamv. He has indicated to use the following git

This includes a new version of php and mariadb

### PHP.INI ###

I also added the following link

ln -s /usr/local/etc/php.ini /etc/php.ini

I could have also changed the Configuration File (php.ini) Path => /usr/local/etc/

### 403 Forbidden ###

Funny thing, nginx is giving me a 403 forbidden error on my hostmaster installation and my newly created sites.

I have to change the permissions of settings.php to 444 instead of 440 (granted by postmaster)

haven't yet found a solution

Submitted by N on March 22, 2012 - 10:25am

The 403 forbidden was caused by the php-fpm user. Wrong user was running the process.

Somehow I didn't link the right file, or whatever. User error.

Submitted by N on March 24, 2012 - 11:23am

Great stuff, and it all works well for me except:

Does anyone get the content of a bona fide php error message in any of their logs with this configuration, and if so, which log?

I have run and re-run the install, double- and triple-checked my work, which is not to say I got it right, and all I ever get is a message saying that php-fpm caught SIGSEGV in its log:

/var/log/nginx/php-fpm.log -> /usr/local/Cellar/php/[version]/var/log/php-fpm.log

if and only if it is the sort of error that causes nginx to throw a 502, and I have yet to get anything at all in


For most PHP errors, like removing a module directory, I just get a 500 and nothing useful anywhere. I don't plan on deleting directories, but when troubleshooting Aegir imports is smack-dab in the path of doing anything, it's useful to see what is missing and why.

Submitted by wamilton on April 23, 2012 - 11:46am

I get this error when i try to ensure the configuration :

bash-3.2# named-checkconf /etc/named.conf
/etc/named.conf:4: open: /etc/rndc.key: file not found

bash-3.2# named-checkzone ld /var/named/db.ld
/var/named/db.ld:1: SOA record not at top of zone (N.ld)
/var/named/db.ld:8: no TTL specified; zone rejected
/var/named/db.ld:10: no TTL specified; zone rejected
/var/named/db.ld:11: no TTL specified; zone rejected
zone ld/IN: loading from master file /var/named/db.ld failed: not at top of zone
zone ld/IN: not loaded due to errors.

any idea why?! thanks

Submitted by Fuentes on May 22, 2013 - 4:00am

Are you at Drupalcon?

Submitted by Brian Gilbert on May 24, 2013 - 1:01am

Add new comment