How to Build for GitHub Enterprise
If you’re building an application that integrates tightly with GitHub, you’re going to see a significant amount of demand for an installable or on-premises version of your product. Large enterprise customers are likely running GitHub Enterprise in a private cloud or private datacenter and they’re reluctant to punch a hole in their firewall to communicate with your cloud-based SaaS application.
At Waffle.io, we’ve navigated these rough waters the last 12 months shipping Waffle Takeout, our on-premises version for GitHub Enterprise customers. These are our pro tips to help you do it faster.
Pro Tip #1: Use the Same Codebase
In Takeout we have special logic to verify you aren’t over your seat limit. Instead of forking our SaaS codebase, we use an environment variable to test whether we need to care about that condition or not.
The same pattern applies for toggling between local dependencies or cloud dependencies, like which database to connect to or where to find static resources like fonts and images.
Our vision is to continuously deliver to both SaaS and on-premises through automated CI tools. We’re on our way there, and keeping our codebases the same between environments is critical.
Pro Tip #2: Use Open Source Replacements for Dependencies
Waffle relies on Pusher.com for realtime communication. Pusher is an amazing service, we highly recommend it. But, Pusher doesn’t offer an on-premises version. Thankfully there are two open source options, Slanger and Poxa.
We went with Poxa and it’s working well for us. Pro Tip #1 still holds true: our application understands the Pusher protocol and isn’t hard coded to use Pusher.com, so configuring Waffle Takeout to use Poxa instead only requires us to change environment variables.
Pro Tip #3: Understand your Enterprise Customers Needs
Our first beta customers were excited about Waffle Takeout, but we quickly discovered some unexpected requirements. Adding SSL and proxy support became our achilles heel but was necessary for enterprise adoption. Ask those questions upfront so you know what to expect.
Pro Tip #4: Do Use Paths, Don’t Use Subdomains
When hosting in the cloud it’s simple to host services as subdomains with DNS configuration. We host our API at https://api.waffle.io, for example.
DNS configuration when behind a firewall is a nightmare. Customers like to kick the tires on a test machine somewhere first, and requiring DNS configuration to wire things up complicates the installation.
If you use subdomains for your SaaS product, consider adding an nginx front door to your application to route traffic using paths, like https://waffle.yourcompany.com/api instead of requiring a subdomain like https://api.waffle.yourcompany.com.
Pro Tip #5: Use Docker!
When you’re ready to start packaging your application for delivery to your enterprise customers, choose Docker. The same consistency Docker creates between your dev, staging and production environments, can now be leveraged for your on-premises deployments too.
The only other option is to ship a VM, and from our experience shipping with Docker images is much faster and our customers prefer it. Docker-based deployments can be installed anywhere, anything from a server closet to the latest & greatest IaaS. We like it so much that we’re considering moving our production stack to Docker as well.
Pro Tip #6: Use Replicated!
If you’re running on the cloud you’re already an expert at building on the shoulders of giants. We use Heroku, Pusher, and Compose to name a few. The same goes for taking your product on-premises. We faced new challenges, and didn’t solve them all by building our own solutions.
Our first release shipped with our own installation process. We learned how hard that was, and today we ship using Replicated’s platform to deliver Waffle Takeout. Working with Replicated is like having a separate dev team to focus on packaging your product, with the right features to help your customers get up and running quickly and the tools to help you support them.
Replicated leverages Docker under-the-hood for the portability we mentioned earlier. In addition, Replicated adds on functionality for managing releases, licensing, installation, configuration, updates, support, monitoring and more.
Each of these features are battle tested in the market across the enterprise versions of Travis CI, npm, Code Climate, Circle CI, Coveralls and others, so you have confidence in it integrating well with GitHub Enterprise and providing your customers with a familiar setup experience.
Pro Tip #7: Celebrate!
Shipping on-premises is hard. Take time to celebrate when you ship your first version or get your first paying customer. We recommend making waffles for your office :).
Originally published at blog.waffle.io on January 26, 2016.