How to create an OSX (pkg) installer (for NodeJS Apps)

Watch on YouTube: youtu.be/p-okATNto7Y

The Installer Trifecta Series

Why pkg? Because it's legit!

When you want to deploy software on a user's system, you want to trust you.

Although there's no real security benefit to using a pkg installer, many users are familiar with it and there's no negative stigma attached to it in the community (as there is with curl -L example.com/install | sudo bash -).

What I'm saying is that .pkg is legit. Perhaps not as legit is .app, but legit enough for many users.

If you find that this tutorial isn't legit enough for you, you may wish to look at Making OS X Installer Packages like a Pro - Xcode4 Developer ID Mountain Lion ready pkg or http://youtu.be/RT7BSn9vWtI

Using 'Hello Node' as our example

This demo is all about installing a NodeJS app as a system service. That demo app we're using is 'Hello Node'.

Here's our project layout

~/HelloNode
    ./HelloNode
        /Gruntfile.js
        /.jshintrc
        /bin
          /server.js
        /node_modules
        /server
          /server.js
        /browser
            /index.jade
            /app.js
        /public
            /index.html
            /app.js
    ./macinstall
        ./pkg
          /Payload.d
              com.hurpdurp.HelloNode.plist
          /Scripts.d
              /preinstall
              /postinstall
              /node-v0.10.4.pkg

You'll need to have installed Xcode and associated tools.

Install Xcode and PackageMaker

You can get Xcode from App Store, but you'll also need Command line tools and Auxiliary tools from https://developer.apple.com/downloads/index.action (Log in and then search for them in Developer Downloads)

From the Auxiliary tools open PackageMaker.

Or without Xcode

You can actually create a .pkg entirely from without ever touching Mac, you just have to do a bit more work.

See How to unpackage and repackage pkgs for a primer.

Add your organization and target

When you first open PackageMaker you'll be prompted to enter your organization.

I just called mine com.hurpdurp.

I also chose the minimum target as OS X 10.5 just because I don't plan on supporting pre-Intel Macs.

Configure the package

There are a few basic options to set for the package as a whole:

Click on the Untitled Package icon on the left and select Configuration.
Set the title to Hello Node
Select Easy Install Only
Uncheck Volume selected by user
Check System Volume
(note that if nothing is selected you'll get warnings / errors)
Type a description "Installs a NodeJS App as System Service."

The other Requirements and Actions tabs aren't important for this demo.

Edit Interface won't be covered either, but go ahead and click on it. It's pretty much self explanatory.

Add the NodeJS App

Either drag the HelloNode/HelloNode folder into the content pane or add it after selecting Project and Add Contents... (or hitting ⌘ +).

Note that there are two clickable items:

The HelloNode by the arrow
The HelloNode with the directory icon

First click on the one by the arrow to configure it:

Click Configuration
Check Hidden (the other two should be selected by default)
Set the destination to /

Now click on the one with the folder icon

Click Configuration
Set Destination to /opt/
Click the Contents tab
Check Include root in package (so that it installs to /opt/HelloNode)
Click Apply Recommendations
(if the owner and group don't change to root, run sudo chown -R root:staff ~/HelloNode/HelloNode)

Add the System Service

Since this is a single file, the Apply Recommendations may not work (it didn't for me).

Before adding it to the content pane sudo chown root:staff ~/HelloNode/macinstall/pkg/Payload.d

Repeat: the permissions and ownership must be correct or the service will not start.

Now add ~/HelloNode/macinstall/pkg/Payload.d/com.hurpdurp.HelloNode.plist just as you did with HelloNode previously.

First click on the one by the arrow to configure it:

Click Configuration
Check Hidden (the other two should be selected by default)
Set the destination to /

Now click on the one with the folder icon

Click Configuration
Set Destination to /Library/LaunchDaemons/
Click the Contents tab
Click Apply Recommendations
Click the Scripts tab
Add ./macinstall/pkg/Scripts.d
Note that preinstall and postinstall are detected automatically
Note that node-v0.10.4.pkg is added as a Script Resource automatically, not as Content.

Build and Run

Now click the build and run button to test the install.

There shouldn't be any warnings or errors and if all is well you should be able to visit http://localhost:5566 and watch the number increment as you hit refresh once the install completes.

If that's the case, everything is work as it ought to. If that isn't the case, there's probably an issue with ownership, permissions, or the system service isn't starting.

Congrats!