Setting up QGIS 2 on MacOS X 10.9 Mavericks

[UPDATE: Find informations about installing QGIS 2.4 in this newer article.]

After a hardware failure on my MacBook Pro’s hard disk in the end of last year (replaced for free within half a day at the Apple Store, thanks to my Apple Care Protection Plan) and an extended christmas and new year holiday I’m currently being struck down by a nasty cold and hence decided I have some spare time on my hands to give the latest Mac OS X version 10.9 “Mavericks” a try. It had been released in October, but I had been too busy to play around with it, so far. Obviously I’m not going to screw up my main production machine, the iMac, but instead designated my old, trusted MacBook Pro to be the guinea-pig.

On a different note, the hardware failure did not cause me any data loss at all, since I have a very thorough (read: paranoid) backup strategy, including two local TimeMachine backups in physically separate locations (one at home, one at my lab’s desk) and three cloud services: CrashPlan to backup the complete data on my iMac and in addition an automated Dropbox workflow and iCloud for all the documents. For my current PhD thesis data I even went two steps further and added manual backups to Google Drive and SkyDrive to the mix.

But back to the topic of this post. After setting up the MacBook from said TimeMachine backup it occurred to me that there was nothing “exclusively” on that machine, hence a Mavericks setup from scratch as opposed to an upgrade would be a feasible option to get a clean system. And that’s what I did. There’s a lot written on the web about how to do that, so I’m not going into details here.

I had read (and heard) about some issues with QGIS after upgrading to Mavericks, so circumventing this trouble seemed like a good idea. Since I have had nothing but good experiences with the QGIS distributions for Mac OS by William Kyngesburye (a.k.a. KyngChaos) I decided to use them again. On his blog he wrote

I don’t plan on upgrading to OS X Mavericks (10.9) soon. […] All packaging will still be done on Lion. I’ve had a few reports that my Lion builds work on Mavericks. At least QGIS, GRASS and the frameworks and Python modules. MapServer/PHP is old and probably will not work. Postgres/PostGIS should be OK.

Accordingly, the QGIS installer is called QGIS 2.0.1-7 for Lion & Mt Lion, but that didn’t put me off, since I know of people successfully running this release on Mavericks. But before installing the actual QGIS one (unfortunately…) needs to make sure that some dependent packages and libraries are installed.

It all starts with the GDAL Complete 1.10 framework package, which can be found here: http://www.kyngchaos.com/software/frameworks#gdal_complete. This will download an image file that contains (amongst others) two packages. First, install the GDAL.pkg, then the numpy.pkg.

One word of (annoyed) advice here: Mac OS protects you from opening and running files from unidentified developers. Well, it tries to do so, by making it impossible to open/run them by double-clicking. Instead, you will have to right-click it and select “Open” manually. Unfortunately this is the case for all files I reference in the course of this blog post…

After having successfully installed GDAL and numpy, you will need to install the FreeType framework v2.4.10-1 and the UnixImageIO framework v1.4.3, both can be found here: http://www.kyngchaos.com/software/frameworks. Again these disk images contain package files that need to be installed.

These two frameworks are prerequisite for installing the Matplotlib Python module, which can be found here: http://www.kyngchaos.com/software/python. Needless to say that the disk image contains a package file that needs to be installed.

Then, and only then do we have all the necessary frameworks and packages that QGIS itself depends on, hence we can proceed to install the beast itself. The QGIS installer can be found here: http://www.kyngchaos.com/software/qgis and comes in at ~160MB. Notice that the complete installation of QGIS including all aforementioned frameworks will occupy roughly half a gigabyte of space on the hard drive.

If everything went smooth you should now be able to startup QGIS for the first time and be presented with the UI and should also be able to load and display some data (here, a SHP file):

QGIS 2.0 on MacOS X 10.9 Mavericks

QGIS 2.0 on MacOS X 10.9 Mavericks

Now that was easy. Too easy you say? Well, so did I, and went on to setup my MacBook in a way that allows me to access the PostgreSQL database I’m running on my iMac. Local access from within my home network would be sufficient for now.

The first step to do so was installing the PostgreSQL client files on my MacBook. Again I relied on the KyngChaos releases, which can be found here: http://www.kyngchaos.com/software/postgres. I personally chose the PostgreSQL Client-only 9.2.4-2, since my database is also running on version 9.2 and I don’t want to run into any version-related trouble. The installation itself is easy, since the downloaded disk image once again offers only one package file to chose from.

Now my MacBook should be ready to act as a client for a PostgreSQL database, but apart from accessing it from within QGIS I also wanted a graphical user interface to do more advanced (also non-GIS-related) stuff on the database from the client. My choice as a PostgreSQL UI has always been pgAdmin, so I downloaded the pgAdmin III 1.8.1 client from here: http://www.pgadmin.org/download/macosx.php. To install it you just drag the .app file contained in the disk image and drop it into your Applications folder.

Starting it up and entering the server credentials should do the trick. Should. In my case, and chances are in most cases, this is what you will be confronted with:

Error message: Access to PostgreSQL database from external host denied

Error message: Access to PostgreSQL database from external host denied

Luckily both pgAdmin and PostgreSQL are quite helpful in telling us what went wrong (we don’t have access permission on that server) and how to fix it (grant us access to the server). This is where the (slightly) nasty stuff starts: we need to tell our PostgreSQL database server that it’s OK if our client tries to connect to it. To do this we need to edit the pg_hba.conf configuration file on the server machine. If you’re unsure where to find it, just issue this command on the terminal:

ps aux | grep postgres

That should generate output such as this:

postgres          1800   1.5 19.4 11071856 6500928   ??  Rs    5 114  170:48.24 postgres: autovacuum worker process   maindb  
postgres         97897   1.0 18.5 11071852 6212236   ??  Ss   171213  415:03.05 postgres: autovacuum worker process   maindb  
postgres         68808   0.0 14.5 11088964 4874860   ??  Ss   日04PM 1641:04.02 postgres: postgres maindb ::1(50701) idle  
postgres         68639   0.0  3.5 11069500 1183764   ??  Ss   日03PM   0:03.30 postgres: postgres maindb ::1(50697) idle  
postgres         48357   0.0  1.7 11069500 561524   ??  Ss   土02PM   0:01.29 postgres: postgres ssddb ::1(62592) idle  
postgres         28171   0.0  0.2 11060840  75940   ??  Ss    6 114    0:00.24 postgres: postgres postgres ::1(54414) idle  
postgres           545   0.0  0.0  2443172    736   ??  Ss   241113   12:00.24 postgres: stats collector process     
postgres           544   0.0  0.0 11055208   2768   ??  Ss   241113    3:00.73 postgres: autovacuum launcher process     
postgres           543   0.0  0.1 11055080  16860   ??  Ss   241113  122:11.17 postgres: wal writer process     
postgres           542   0.0 25.2 11055080 8461880   ??  Ss   241113   15:25.43 postgres: writer process     
postgres           541   0.0 25.5 11080140 8562424   ??  Ss   241113  450:33.48 postgres: checkpointer process     
postgres           538   0.0  0.3 11050980  96712   ??  S    241113    1:24.68 /opt/local/lib/postgresql92/bin/postgres -D /opt/local/var/db/postgresql92/defaultdb
root               111   0.0  0.0  2503188    500   ??  Ss   241113    0:09.78 /opt/local/bin/daemondo --label=postgresql92-server --start-cmd /opt/local/etc/LaunchDaemons/org.macports.postgresql92-server/postgresql92-server.wrapper start ; --stop-cmd /opt/local/etc/LaunchDaemons/org.macports.postgresql92-server/postgresql92-server.wrapper stop ; --restart-cmd /opt/local/etc/LaunchDaemons/org.macports.postgresql92-server/postgresql92-server.wrapper restart ; --pid=none
konstantingreger 98497   0.0  0.0  2432768    620 s000  R+    5:04PM   0:00.00 grep postgres

Somewhere in there you should find a line (marked above) that reveals the path to your server instance after -D, in my case /opt/local/var/db/postgresql92/defaultdb. In that folder you will also find the pg_hba.conf file we’re looking for, so open that in a text editor of your choice.

You will see many many comments (marked by #) and all the access rules for your server. The easiest (albeit quite unsafe, see below) way to fix it is to simply add this line to the end of that file:

host    all    all    192.168.0.0/24    trust

Please notice that PostgreSQL couldn’t care less about the number of spaces and/or tabs between the entries, these are just for us humans so it looks nice and tidy and can be easily understood. Please note that the keyword trust in the end is quite dangerous. It makes the server accept all connection requests from all servers within the given IP address range (here: my local network domain) without asking who’s trying to connect. You should never use trust in a production environment or on a database server that is accessible from the internet!

Next and final step is to restart the database server, so PostgreSQL knows about our new connection policy. This can again be done from within a terminal session using:

sudo su - postgres
/opt/local/lib/postgresql92/bin/pg_ctl restart -D /opt/local/var/db/postgresql92/defaultdb -m fast

Please note that I had to temporarily login as user postgres to restart the server. Also, you might have to replace the folder references to the one you established above. The last command should produce output similar to this:

waiting for server to shut down.............................................................. done
server stopped
server starting

LOG:  database system was shut down at 2014-01-14 17:17:54 JST
LOG:  database system is ready to accept connections
LOG:  autovacuum launcher started

Since we didn’t tell the server a location to write its log messages it starts to write them to the current console window. If you want to change that behavior, please refer to the official pg_ctl documentation. Once you’ve seen everything you needed to see, you can safely close this terminal window.

Final check: can we now connect remotely to our database server?

Successfully connected to PostgreSQL database from external host (pgAdmin)

Successfully connected to PostgreSQL database from external host (pgAdmin)

Looks good from within pgAdmin. How about QGIS?

Successfully connected to PostgreSQL database from external host (QGIS)

Successfully connected to PostgreSQL database from external host (QGIS)

Looks good! Finally, productive work can commence… By the way, so far I didn’t run into any glitches or weirdnesses of Mac OS X 10.9 itself, but I’m also relatively unimpressed with its benefits (read: haven’t found any, yet). It’s a good thing the OS upgrade was free.

Please let me know in the comments if you encountered any problems while following these instructions.

10 Comments

  1. Hi,
    I’m running QGIS 2.0.1-Dufour on a MacBook Air, with OS X Mavericks, version 10.9.2 and Server 3.0.3. I have successfully installed the server and through phppgAdmin set up a database. I am now ready to add PostGIS layers, but cannot get QGIS to connect to the localhost server. I followed your instructions above, found the pg_hba_config file and checked the settings. The first uncommented line says: local all all trust, so ostensibly that is in order, but I can’t connect. What else can I try? I’m a newbie at all of this. Rgds, Pine.

    Reply

    1. Hmm, is the local all all trust line the only uncommented line in your pg_hba.conf file? If so, this might be the culprit. The official documentation mentions that local “matches connection attempts using Unix-domain sockets.” host on the other hand deals with TCP/IP connections, and that’s what we need here. May I suggest you try adding the following very generic and very dangerous line I used in my example: host all all 192.168.0.0/24 trust Obviously you will have to make sure the IP address range matches your local settings. If this works (it basically allows all kinds of connections from all addresses in the address range without asking, hence very dangerous!) you could start from there and limit access to your client only. Please let me know how it went!

      Reply

      1. In fact, there are 3 uncommented lines in the pg_hba.config file, one of which is “host all all 127.0.0.1/32 trust” and the other “host all all ::1/128 trust”.

        My server is not public, as I’m at the development stage on my MacBook Air.

        Reply

        1. Well, the first line deals only with connections from the localhost (127.0.0.1).
          The second is setup for connections using IPv6 addresses -- I remember I had some issues with that in the past.
          Again, may I suggest you temporarily include the line I mentioned in my post and in my last comment, and see what happens?

          Reply

          1. Did what you suggested, still no success in getting QGIS to connect. Any other suggestions?

          2. One more thing you can try is checking the listen_address option in your postgresql.conf file. It should say listen_addresses '*' to accept connections from any IP address.

  2. How come my Qgis GUI looks pixelated? I was also told by my computer to download Java SE 6 Runtime…any thoughts on why?

    Reply

    1. I’m sorry, but this question is way too unspecific to be answered in any helpful way. Which version of QGIS? What host OS? How is the Java download (update?) related to the problem? What do you mean by “pixelated”? Also, while I’m happy to help where I can, this question appears to be completely unrelated to the topic of the article, so I suggest you gather some more background information about the problem, sit down to write a more concise and informative explanation of the issue (cf. these guidelines), and post it somewhere more fitting. May I suggest GIS StackOverflow for starters? Or any QGIS forum, newsgroup or mailing list.
      Good luck, and don’t let small bumps let you scare away from using open source software and especially QGIS!

      Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

*