« A perfect analysis | Main | How to deal with a New Media Douchebag talking shit »

Over the years, I've written a lot about installers. Mostly about the bad ones, because face it, the good ones are doing it right already. (Yes, that means if I haven't yelled at you about it, I like your installer, you're doing it right, or at least right enough. Go and have a cookie on me, you're all good.)

Some of this is due to the fact that I just like to see things done correctly, but most of it is because due to my career, (IT), I have to care about installers more than most. In many cases, I care more about the installer than what it's installing, because that's the only part of the software I will ever use. I'm not going to be using Flash anytime soon, for one, I kind of hate Flash, it's a fucking pox on the web, and getting worse, but I will have to install it. Many times.

The same for lots of other software. I'm going to have to install stuff hundreds of times, and I may never use it. So installers: I care.

While this article is going to focus on the Mac and the Mac OS, the basic principles apply to really any platform. With that, here are my installer commandments, the order is convenient, nothing more:

1. Thou shalt use native installers wherever possible.

   In general, there's no excuse for not using the native installers for a platform. Rolling your own, while tempting and perhaps satisfying to the ego is usually stupid, because you are simply creating more complexity for the user, (it will behave different than what they're used to), and it will piss off IT people, (it won't work with their tools for pushing applications out to users). There's very few exceptions, and most of them deal with cross platform, and are only temporary. If you have to install the same application on multiple platforms, and one platform's installer isn't up to the job, and you have to write a custom installer for one platform, then there is some sense in using that for all the platforms you support. However, this is a sign that something in your application or your process is seriously cocked up, and that you need to include "ease of install" as a requirement for your next version. This leads into my next commandment.



2. Thou shalt give the installation of thy application a higher priority than the beer you buy for the ship party

   Look, writing installers is not glamorous, it's tedious, and it's also completely fucking important. The installer is either the first or second experience someone has with your work. (It's second if physical media, first if a download.) I see these messed up installers that just do stupid shit, or make you enter in stupid codes, (can we all finally agree that activation is stupid, and has never prevented piracy, and maybe STOP TORTURING YOUR CUSTOMERS), or quit every running process or all of the above, and I wonder if the people who did this really thought about what they were doing. Did you really want someone's first experience with your work to make them hate you? That installer, the process of getting bits to where they should be is the very first interaction someone one has with your actual code, and yet, too many of you out there give it less thought than clean socks!

   Do you like it when people hate you? No? So stop making them. Give your installers the priority they should have, and make the install smooth, painless, and forgettable.

3. Thou shalt remember that thy program will probably be installed remotely, and test accordingly.

   We'll get into details on how to test later, but, if you do all your installer planning based on people only installing it on one computer at a time...well the kinder opinion here is that you don't really have a clue about things. I'll lay odds that at some point, someone, somewhere is going to have to install your application on many, many computers at once. If you don't test for that, shit will go wrong, it will be your fault, and you're going to get called a dumbass by IT staff. That won't be slander nor libel, as they'll be right. Not testing remote installs of your application does in fact, make you a dumbass. Do you want to be a dumbass? No? Then test that remote install.



4. Thou shalt remember that it is thy job to do the hard work so thy customer doesn't have to

   That means you handle the edge cases. You figure out how to gracefully deal with things like old versions of your application left lying around. You figure out how to deal with network home dirs, and home directories in weird places, and all the rest. You, you, you, it is your responsibility. All the user should have to do, ever, is double-click the installer package, and at most, enter an administrator password. If they have to serialize the application, let them do that on first run. Why? Because again, you cannot guarantee that your installer will only be used by a physical person. It may be part of a script. So you need to make sure that other than that administrator password, there's no other human interaction needed.

5. Thou shalt do everything possible to avoid an administrator password, and thou shalt never, ever, ever require an administrator password to start up thy application.

   The first is difficult, because well, if you want to install it in /Applications, you need the user doing the install to be in the administrator group. However, you should always give the option to install in a user home directory. In that case, can your application handle this? Can your application run if all of it is installed in a user's home directory? Can it run if it has things in ~/Library/whatever instead of /Library? If not, can you make it work that way? You'd be amazed at how many people would appreciate this, even if you don't understand why this matters. If nothing else, it shows that you, the dev, are thinking, and doing the extra work to make that install go beyond just not sucking, and into the realm of "now that is how this should work.

   On the second bit. I'm not talking about applications that, as a part of their functionality do things that require an administrator password, but they're kind of included. What I am specifically talking about is first-run shit that makes you enter an administrator password just to start the application and have it sit there, quietly idling. "First-run" configuration is a part of the installation, and while it's kind of stupid, it's understandable, especially for applications that may be run by multiple people on multiple machines. However, there is never an excuse for first-run requiring an administrator password just to start the application. Why? Because if you install that application on a couple hundred machines, what happens? Yeah. Exactly. Especially if it's first-run per user not just per machine. Adobe Acrobat, both Pro and Reader are the poster children here, and in their case, it's not for critical functionality. Why, instead of quitting the application for lack of an administrator password, just pop a dialog that says "Hey! You're not an administrator on this machine. If you can enter an administrator password, click "Authenticate" and I'll enable the web browser and Office functionality. If not, click "Continue", and you can still use the rest of my functionality, but those parts won't work."

   But that shit about "You can't even start this application without an administrator password? That's just fucking stupid. If there's nothing your application will do without an administrator password, why not just make it a command-line utility...nah, that's stupid too, even a command-line application should be able to tell me what it does, even if I need an administrator password to do any of it. Just stop it.

6. Thou shalt always assume there is a network, and that your users are on it

   There is nothing that shows a complete lack of thought for the user than "You cannot install this from a network volume" dialogs. First, fuck you, there's nothing in iWork '09 that makes me think this shouldn't work. What, Keynote doesn't work because I didn't install it from a local version? Yes, I deliberately used an Apple example, because they have the least excuse for this.

   Folks, not only are networks common, they're probably more common than not outside of single person homes. Everyone and their brother has some little NAS set up, even if it's just a Time Capsule. You cannot, for any reason, assume that your application is a special snowflake that will never be used on a network. (as a corollary, stop with the "we don't support working directly from the network. That's stupid too, but not an installer issue.) You simply have to do the work, and make your installers work from a network share. By that, I mean pretty much every kind of network share than an unmodified copy of the current version of Mac OS X will support. So, AFP, SMB, NFS, and WebDAV at a minimum. Extra points for other things, but those must work out of the box. Again, that's why people pay you for your work, so that they don't have to deal with it. "It just works" is your goal at all times.

   Oh, no, freeware doesn't get a bye here. Just because it's free doesn't mean you can be lazy. If you're going to spend the time to write the application, then spend the time to make your installer not suck.

7. Thou shalt never, ever, ever lie or mislead the user about your installer and what it's installing

   Adobe Reader? Looking at you pal. Making your installer look like a platform standard installer, but then having that not really be what it is? That's just bullshit, and means that not only did you fail to use a native installer, but you also lied to your users about it. That is unforgivable. If you are going to use MSI or an Apple Package, or whatever you're using for whatever build of Linux, then actually use those technologies, don't just wrap your own special silliness in them. Insulting and lying to your users is always wrong. Not stupid. Wrong. Probably evil too, and it makes me wonder just what else you're lying about.

   Along with the whole "lying" meme, don't try to sneak shit in. Adobe Bridge & Device Central, you didn't think I'd forgotten about you, did you? If you have to, regardless of reason, embed another application in your application bundle, i.e. a full working copy of Opera, then you need to tell people this, in BIG! GIANT! FONTS! IN ALARMING COLORS! Otherwise, you're sneaking shit in, so you're not just lying, but you're trying to cover that lying up, and that's even worse. (Corollary: if you put it in your application, you have to keep it up to date and secure. Telling me that "oh, you can't easily double-click it, so it's not a security hazard" not only means you're lying about it, but you're being a douchebag about it to boot. But again, not a direct installer issue)

8. Thou shalt use the least amount of archiving/compression possible

   No one needs a fucking gzipped, tarred, disk image. NO ONE. If you're going to use a disk image, then learn how to do it right, and just use the disk image compression. Conversely, if you're going to do it as a tar.gz, then don't use a disk image. It makes you look stupid. Not as stupid as some of the real idiots in this category, like Epson who used a binhexed, Stuffed installer that only installed the installer which then let you install the drivers. That's not the worst i've seen. I've seen them add in tar and disk images to that shit too. Makes me want to take a bunch of angel dust and do whatever the voices tell me to do to them. Seriously, this is just stupid, but I still see it. What, you like looking like an idiot?

9. Thou shalt stop using Installer VISE, Installanywhere, pseudo-installers, and other such tripe

   Seriously. Just stop. It's a pain in the ass to deal with, and while I have a twinge of guilt at advocating an action that will essentially put a company out of business, that product has been causing people too much pain for too long and I still see it being used. There's only like one or two products on the Mac side that directly supports it, there's about the same on the Windows side, and I think they may be the same products.

   The same for InstallAnywhere, or however you capitalize it. I don't care that it makes it easier for you to write the installer, I care that it makes installing it suck. I'm not paying, in either cash or time, for you to not be put out. You want people to use or recommend your application? Then put on your big-boy pants, and don't make my life suck to save yourself some overhead. I don't care that it's not easy for you to write separate platform-native installers. Unless your ass is coming over to install your application for me, and not charging me extra for it, then your convenience is of no matter. You want to be a developer, well, there's more to it than algorithmic efficiency.

   Oh, and the pseudo-installers? Those are the crapfest like the Adobe "Run the installer to download the code that I'm going to install. See? The installer's smaller, isn't that great?" stupidity?

   NO

   IT IS NOT GREAT

   IT IS STUPID, BECAUSE I STILL HAVE TO DOWNLOAD THE BITS I'M GOING TO INSTALL, AND IT MAKES DOING REMOTE INSTALLS ESSENTIALLY IMPOSSIBLE.

   Pseudo-installers are stupid, and a false savings, because in the end, no time, and no bandwidth is saved, and you create more work for your customers because if they want to do network installs, they have to do a lot more work to deal with your "I'M SAVING...NOTHING! YAAAAAY" idiocy. Just stop it.

10. Thou shalt never open up Finder windows to show people thy icon coolness without making sure there is a user logged in, and the install is happening in their user context. Nor shall you pop windows to promote thy product, requiring a user action, or an installer modification to handle it.

    First, let me say that the fact Apple allows or ever allowed the Finder to start outside of a user login context is pretty fuckin' stupid, and yes, I did in fact file a security bug about it. They blew me off. I don't publicize it much because it's not like I'm not still calling them stupid about it. Besides, one day, it will publicly blow up in their face, and folks, lemme tell you, there is nothing so sweet, so satisfying, in the English language as "I TOLD YOU SO". I get tingly just thinking about it.

    However, this still falls under the whole "do your own work" heading. Regardless of Apple being stupid, this is something you need to check for, and make sure your installer does the right thing. I've seen almost every company with an installer make this mistake, I've called them out on it as I can, and usually, afterwards, (because face it, this is SO stupid that I'm justified in being a complete prick about calling them out on it), they fix it. But there's always the denial phase, or in some cases, the "I'm angry that you called me out about something that was really stupid in a mean way, so I'll threaten to not fix it, just to show you that meanies never win."

    Okay Rainbow Brite, you just try that. Here's a hint though, I'll still win this argument in the end. Opening up root Finder sessions is always stupid, and you always lose for doing it. If nothing else it shows that you didn't really test your installer.

    The last one? No, I still haven't forgiven the QuickTime team for that shit. It's bad enough that the entire QTPro thing is still around, and still stupid, even if I do understand the reasons behind it. But that fucking miserable popup screen? You still haven't made up for the pain that caused.
    

11. Thou shalt name all thy installed directories in clear <supported install language> and thou shalt not create more install locations than thou has to. Also, clear documentation on what goes where is nice too.

    Adobe's the easiest target here, but no one's really innocent. I get that you do have to put stuff in various places in /Library, and ~/Library, etc. Especially if you're following Apple's guidelines. But, is it so hard to name things clearly? Is it a herculean labor to make your directory tree clear, concise and documented? Is there some unavoidable reason why I have to have this on my machine:

    /Library/Application Support/Adobe/SoftwareUpdates/{EB052E23-F2EB-4A56-AD48-5051F50BF3BB}

    Come on people, that's just stupid.

    It's not just Adobe. Here's one from EMC Retrospect:

    /Library/Application Support/13650078

    Mozilla (Surprise, Open Source is not immune to the stupid any more than non-Open Source):

    /Library/Application Support/Mozilla/Extensions/{ec8030f7-c20a-464f-9b0e-13a3a9e97384}

    Apple, would it kill you to move all your stuff in /Library/Application Support to the Apple folder?
    

There, ten eleven commandments. Pretty damned simple ones, and most of them don't take a lot of 'splainin', except for the Third Commandment, because if you aren't sure about what's involved, then it's easy to screw it up.

About Network/Remote installs

The fact that I have to explain this is really strange for me, because to me, this is normal ops, but then again, I regularly have a few hundred machines to deal with. For a small dev shop, that's not going to be a realistic option.

So, first, spend the money, and at least get a Mac Mini to test on. (I'm only going to talk about the Mac side, since this involves specifics, but the general principles apply to all.) If you're only supporting Intel architecture, then only get an Intel Mini. If you're supporting PPC, then get on ebay, or find a used PPC Mac to test on. Make sure it will run 10.5.X, so that you can properly test it.

Now, if you want to get really cool, you can create multiple boot partitions with different versions, and that's cool if you do. It speaks of a care for details, and that's all this is, detail work. However, you're probably safe with, at a minimum, testing Mac OS X 10.5 on Intel, and Tiger/Leopard on PPC. (Finding an Intel machine that will boot Mac OS X 10.4 can be tricky, and I don't want you trying to buy 3-4 machines here, unless you can afford it.)

In addition, you need to buy a copy of Apple Remote Desktop. Just get the ten-client license. Anything more, and you're kind of testing Apple Remote Desktop more than your installer. However, if you want to get the unlimited client license, and test on a hundred machines? Thank you, I love you. I'd also recommend getting a ten-client license of Mac OS X Server, unless you're okay with manually creating WebDAV and NFS shares. However, keep in mind that your product may in fact be installed on Mac OS X Server, so at least get a current version of that and put it on one of your test machines. This is where a minimal dual-boot setup is a good idea.

So that's a basic test setup, and while it's not cheap, it's not hugely expensive. If it is a problem, then you can probably get communal with some other small devs and have a community test network.

We'll assume that you at least test the "Sit in front of the machine and double click the installer from local media" part. If you aren't even testing that, then I really don't like you very much, because dude, that's pretty fuckin' lazy.

Installing from a Network Volume

So, first, test installing it via double-click from a network volume. Luckily, creating AFP/SMB shares is easy, even without Mac OS X Server. Just put your installer up on a shared directory, then go to another machine and try to install it from that network share. If it doesn't work, fix that, it's a bug. Really, it's a bug. If you have Mac OS X Server, or can do it buy hand, create an NFS and a WebDAV share, (hint, they can all be the same directory) and install it from each, at least once. No, this is not going to cover the full range, but it will get you past the gross issues, like "Won't install at all".

If you have the budget for multiple types of network authentication setups, sharing methods, great, the more testing the better. But, at least test from AFP/SMB/NFS/WebDAV.

Also, if you find yourself hating your uninstall process, well, isn't this a fantastic time to clean that up too? Hey look, you're getting 2x the testing done, and removing pain points for your users too.

Installing via SSH & the installer utility

Next, test your installer against the command-line installer utility. This is where you get to play with things like ssh and sftp. Note, you need to test this in three conditions:

1. Non-admin user logged in


2. Admin user logged in


3. No one logged in

Extra points if you test against Fast User Switching, but those three will cover huge chunks of typical use of the installer utility. Copy your installer over to the client via SFTP/FTP/etc., then install it via the installer utility. Did it work? Did it behave appropriately for each case? A big thing here is that when this is happening, the user should not know. On a remote install, it should be silent. No dialogs, progress bars, stuff in the Dock, or drives mounted in a visible manner. It should be stealthy, before, during, and after the install.

One thing to test as well...make a minor change to your code, (REALLY minor, just enough for it to be different. Comments, whatever), then install that "update" via the installer utility. When you're testing in the "User is logged in" context, open the application, and see what happens. If there's strange things happening, you want to know before you release that first real update, and get the angry emails. I know it seems stupid, but a lot of times, we aren't going to be able to ensure that people have quit your application before we install, so you need to test for that so your installer can handle that gracefully. This happens far more than you think, especially in the Apple Remote Desktop & similar situations. That Task Server means you get no luxury of assuming squat about anything.

Another thing to pay attention to: Logging. I'm not going to say there's no such thing as too much logging, Adobe proved that wrong with CS 3 & 4. However, if the install fails, that should be logged, either via syslog, or if you're using your own log, (which of course, you'll have documented in a clear manner), there. Please do provide as much information as your installer/app can about the error. IT people are, (or should be) good about reading logs when things go wrong. In fact, if we can, we'll have the log up while we install, at least in initial testing. Don't be all stupid about it like CS3/CS4 though. A good rule of thumb is that if something worked correctly, I don't need reassurance. I assume it will work. It's when it doesn't work that I need details.

Installing via Apple Remote Desktop and other similar systems

I'm only going to talk about Apple Remote Desktop here because it's a really common, if not the most common managed install application, and, if it works in Apple Remote Desktop, then it should work with all the others. If not, then most of them have demo versions you can play with, or a couple of messages to the IT community will probably get you people who will help you out in exchange for a free license or two for your application.

I'm assuming you can get ARD working on your own. If not, there's a lot of info out there, and an ARD mailing list, (remote-desktop@lists.apple.com, go here to sign up for it, search archives, etc.), and trust me, if you ask for help because you want to test your installer against Apple Remote Desktop, people will fall all over themselves to help you, because that will help them.

So there are a few ways to test with Apple Remote Desktop. First, keep in mind the earlier three conditions, they still apply. In addition, you want to test:

1. With Apple Remote Desktop's remote install functionality, both with a Task Server and without


2. By copying the installer over to the client(s) via Apple Remote Desktop's copy functionality, then installing with installer from a separate SSH session


3. By copying the installer over to the client(s) via Apple Remote Desktop's copy functionality, then installing with installer started with Apple Remote Desktop's "Send Unix Command", and not a separate SSH session

The reason testing with the Task Server is important is because of what the Task Server does. Let's say that you have a big network with laptops. ("Big" can be 20 or so. It's not a precise term.) Now, getting all these laptops in the same place at the same time is going to be tricky. What the Task Server will do is wait for machines that you've told it to install something on to show up on the network, and then, as they show up, run the installer you've told it to against them.

This is great for IT people and users, because it gives us a lot of flexibility and convenience. It sucks for you, because there's no way to assume what the heck is going to be going on with a given client when the install happens. (If you're making assumptions that are not absolutely necessary, and cannot be removed, then you have to use the Task Server a lot, because that's where most of your assumptions are going to blow up in your face.

One caveat: to test with the Task Server or Apple Remote Desktop's installer functionality, you must use Apple installer packages. Period. Also, if you're lying and wrapping some other installer inside of the Apple installer, this is where it's going to blow up, and make people hate you. Again, the Seventh Commandment, don't lie about installers will keep you from this.

True, testing with Apple Remote Desktop complicates your test matrix, but if your stuff works with Apple Remote Desktop, then it's probably going work with all the rest. If nothing else, it means your stuff will work with Apple's tools, and gives you high probability for third party tools without having to buy and configure them all. That's pretty efficient, and takes care of what, 80% to 90+% of all the problems you'll see.

Note: If you're rolling your own installer, you still have to test with all these conditions, and you'll be doing a lot more work to fix any problems you find. Are you sure rolling your own is really a good idea? Really?

Conclusion

Look, I'm not going to sit here and pretend this kind of thing is fun. Installers are tedious and boring and they suck, they always suck. The best you can hope for here is "no problems". Don't go for "delight" because chances are, that will blow up in your face. Instead go for "transparent and doesn't require extra work". With installers, you want boring and forgettable, not exciting and flashy. It seems sad, but I love me a boring installer. Most IT people do, because boring = less work, and we love installers that require less work.

Also, this is not the last word in installing. It's just a collection of things I've seen over the years that annoyed me, or made my life suck, and so I'm trying to maybe help people avoid making the same mistakes as others. There's a lot more ways you can test things, but I tried to maybe give you some pointers along the way that can help you avoid hate mail. This is the start, young grasshopper, not the finish.

As well, you don't have to do this all alone. The IT community has a huge vested interest in your installer not sucking, perhaps as much as you do. Asking for help and offering, where appropriate, free licenses or beer, is going to get you some really detailed feedback. Maybe more than you wanted, but they're helping you help them, so they're motivated. Don't be afraid to ask. Along those lines, don't take the criticism personally. Keep in mind that a lot of it is written "in the moment" as in "your installer is killing days of my life, and this is what i'm feeling". You, or at least your product, is probably going to get called names, and damned rude ones at that. Relax. We don't hate you, we hate what your installer is doing. If you can differentiate the two, you'll do well.

Finally, now Matt will stop bugging me to do this article. So there's that.

Mac IT Resources

Some resources that can help you in your quest to create better installers, and also let you hear about all kinds of issues before you fall into them.

Apple Mailing Lists

In addition to the ARD list:

• Client-Management: A list that deals with various client management issues in Mac OS X Server environments


• Macos-x-server: The "main" Apple IT list. Warning, it's high volume, and high emotion. Don't take it personally, it's just a room full of IT people. We're cranky.


• Security-announce: Low volume announce-only list for security updates. You really want to be on this, as it can help you anticipate problems.


• System-Imaging: A list for people working with Apple's system imaging tools. This is really just a big installer list, if you think about it.


• Xsan-users: I didn't talk about Xsan, because it's still a bit esoteric, and really expensive to implement, but if you can get time on an Xsan for testing, or want to get someone to help you test against an Xsan, this would be the place to start.

Non-Apple Mailing Lists

• Tidbits Talk: It's not an IT list per se, but, it has a huge cross-section of people from the Mac user community on it, and is invaluable if you want to get non-IT feedback on your installer, and of course, you want that.
• Mac Enterprise List: Or "Mac-E" for short. This is not the oldest Mac IT-focused mailing list, but it is the one that is the most "grown-up" in how people behave on it. It's also got a really high concentration of Higher Ed IT types on it, and they are really good at finding bugs you'd never even think to use. Note: Radmind fans are a little weird, it's not just you.
• Mac-Mgrs list: Technically, it might stand for "Mac-Managers" but that was almost an Apple product in the Mac OS 9 days, so it's just "Mac-Mgrs". It's a great list to lurk on, low-traffic, low noise, but for the love of $DEITY$, make sure you understand the rules before you post, especially if it's not a specific problem. Chuck is cranky and expects people to RTFM before posting. So do all the subscribers.

Apple Web Sites

Apple's Developer site is the only one worth mentioning, but then if you're writing applications, you know about it already. Apple's "IT" sites are a bit of a waste, and occasionally current.

Non-Apple sites

I'm not going to link to MacFixIt, that site went to hell after Ted sold it, and it's worthless unless you want to repair permissions every thirty seconds.

• AFP548.com: Absolutely fantastic site, one of the best resources out there.
• MacEnterprise: Not just a mailing list. Webcasts, articles, you name it.
• Managing OS X: Greg Neagle's site. Greg writes a lot about issues that would have a direct effect on installers and imaging. He's really smart, and well worth listening to.
• Jaharmi's Irreality: Jeremy Reichman's site. He doesn't update often, but his S/N ratio rocks. Another really smart guy who you should listen to.
• mind the explanatory gap: Nigel Kersten, who is deep into things like imaging, the OS in general and Puppet.
• 318 Tech Journal: Charles Edge's site. He's got a lot of good cross-platform networking info.

Technorati Tags:
Installers MATTER

Comments