Table of Contents
Deploying Go Web Apps to Heroku
- Cloud Computing Service Levels
- Create an account on Heroku
- Install the Heroku Command Line Interface (CLI)
- Prepare a web app
- Use Git to deploy our app to Heroku
- Create a Procfile
- Install Godep
- Declare app dependencies
- Using godep with our project
- Add these new files to git
- Create and Deploy the app
- A brief note by Gunnar Aasen
Who is the book for?
Are you new to Go and taking part in the Go Challenge? Some of the challenges might require you to create a web app in Go and deploy it to Heroku. Don’t know how? If yes, then this eBook is for you and will show you how it’s done.
What will you learn?
In the end, you will understand and know the how to deploy web apps to Heroku.
Using Code Examples
All of the code in this book can be used pretty much anywhere and anyhow you please.
How to Contact Me
I can be reached via e-mail at
firstname.lastname@example.org. Please contact me if you have any questions, comments, kudos or criticism on the eBook. Constructive criticism is definitely appreciated; I want this eBook to get better through your feedback.
Thanks for downloading and checking out this eBook. As part of the lean publishing philosophy, you’ll be able to interact with me as the eBook is completed. I’ll be able to change things, reorganize parts, and generally make a better eBook. I hope you enjoy.
Deploying Go Web Apps to Heroku
There are plenty of definitions for “cloud computing” online, and for the most part, they generally point to the same thing: taking applications and running them on infrastructure other than your own. Companies or individuals who offload or effectively “outsource” their hardware and/or applications are running those apps “in the cloud.”
Cloud Computing Service Levels
In the figure below, you can see how the analyst firm Gartner segregates cloud computing into three distinct classes of service.
Let’s start at the highest level: software applications that are only available online fall into the “Software-as-a-Service” category, also known as “SaaS”. The simplest example to understand is e-mail. For personal e-mail, people typically select from a variety of free web-based e-mail servers such as Google’s Gmail, Yahoo!Mail, or Microsoft’s Hotmail, rather than setting up all of the above through their provider. Not only is it “free” (supported through advertising), but users are freed from any additional server maintenance. Because these applications run (and store their data online), users no longer need to worry about managing, saving, and backing up their files. Of course, now it becomes Google’s responsibility to ensure that your data is safe and secure. Other examples of SaaS include Salesforce, IBM’s NetSuite, and online games.
On the opposite end of the spectrum, we have “Infrastructure-as-a-Service,” or “IaaS,” where you outsource the hardware. In such cases, it’s not just the computing power that you rent; it also includes power, cooling, and networking. Furthermore, it’s more than likely that you’ll need storage as well. Generally IaaS is this combination of compute and cloud storage.
When you choose to run your applications at this cloud service level, you’re responsible for everything on the stack that is required to operate above it. By this, we mean necessities such as the operating system followed by additional (yet optional services) like database servers, web servers, load-balancing, monitoring, reporting, logging, middleware, etc. Furthermore, you’re responsible for all hardware and software upgrades, patches, security fixes, and licensing, any of which can affect your application’s software stack in a major way.
In the middle, we have “Platform-as-a-Service,” or “PaaS.” At this service level, the vendor takes care of the underlying infrastructure for you, giving you only a platform with which to (build and) host your application(s). Gone are the hardware concerns of IaaS, yet with PaaS, you control the application — it’s your code — unlike as the SaaS level where you’re dependent on the cloud software vendor. The only thing you have to worry about is your application itself.
Systems like Google App Engine, Salesforce’s Heroku and force.com, Microsoft Azure, and VMwares Cloud Foundry, all fall under the PaaS umbrella.
A number of Platform-as-a-Service (PaaS) providers allow you to use Go applications on their clouds.
Heroku is a new approach to deploying web applications. Forget about servers; the fundamental unit is the app. Develop locally on your machine just like you always do. When you’re ready to deploy, use the Heroku client gem to create your application in their cloud, then deploy with a single git push. Heroku has full support for Go applications.
We shall soon see how we can deploy an app to Heroku.
I assume that you have:
- Go 1.6+ or 1.7+ installed.
- $GOPATH/bin has been added to your $PATH.
Create an account on Heroku
Please ensure that you are connected to the internet and then create an account on Heroku (obviously do this only once). If you don’t have one, then signup. It’s free and instant. A free account can have up to 5 apps without registering your credit card.
Install the Heroku Command Line Interface (CLI)
The Heroku CLI provides you access to the Heroku Command Line Interface (CLI). Once installed, you’ll have access to the
git command from your command window.
Log in to heroku
Open a command window and create a folder
webapphr under the folder
$GOPATH/src/github.com/SatishTalim/. Change your folder to
Now log in to Heroku using the email address and password you used when creating your Heroku account:
Authenticating is required to allow both the heroku and git commands to operate.
Introduce yourself to Git
On Windows, start the Command Prompt (cmd.exe) to access the command shell.
For all operating users, you now need to identify yourself to Git (you need to do this only once) so that it can properly label the commits you make later on. I am using SatishTalim and email@example.com below:
Substitute in your own user name and email id.
Prepare a web app
In this step, you will prepare a simple Go application that can be deployed.
In the folder
webapphr under the folder
$GOPATH/src/github.com/SatishTalim/ write the program
webapphr.go as follows:
Use Git to deploy our app to Heroku
In order to deploy to Heroku we’ll need the app stored in Git. In the same folder i.e.
Create a Procfile
Procfile, a text file in the root directory of your application (
$GOPATH/src/github.com/SatishTalim/webapphr), to explicitly declare what command should be executed to start your app.
Procfile looks like this:
This declares a single process type,
web, and the command needed to run it. The name
web is important here. It declares that this process type will be attached to the HTTP routing stack of Heroku, and receive web traffic when deployed.
The recommended way to manage Go package dependencies on Heroku is with Godep, which helps build applications reproducibly by fixing their dependencies.
Let us install
$ go get github.com/tools/godep
Declare app dependencies
Heroku recognizes an app as a Go app by the existence of a
Godeps.json file in the
Godeps directory located in your application’s root directory (
Godeps/Godeps.json file is used by
Godep and specifies both the dependencies that are vendored with your application and the version of Go that should be used to compile the application.
When an app is deployed, Heroku reads this file, installs the appropriate Go version and compiles your code using
godep go install ./….
Using godep with our project
In the folder
$ godep save -r
This will save a list of dependencies to the file
Note: Read the contents of
Godeps/_workspace and make sure it looks reasonable.
Godep does not copy files from source repositories that are not tracked in version control. Then commit the whole
Godeps directory to version control, including
Add these new files to git
Now we’re ready to ship this to Heroku.
Create and Deploy the app
In this step, you will first create and then deploy the app to Heroku.
Creating an app on Heroku, prepares Heroku to receive your source code.
When you create an app, a git remote (called
heroku) is also created and associated with your local git repository.
Heroku generates a random name (in this case
stormy-lake-46504) for your app, or you can pass a parameter to specify your own app name.
Now deploy your code:
The application is now deployed.
Visit the app at the URL generated by its app name. As a handy shortcut, you can open the website as follows:
$ heroku open
That’s it — you now have a running Go app on Heroku!
A brief note by Gunnar Aasen
A number of bugs can potentially be encountered in the process of deploying a Go application to Heroku. Many times, a bug can be traced to a misunderstanding of Heroku’s architecture and how it works.
Overall, Heroku applications are expected to follow the “process model” architecture. The process model allows applications, and web applications in particular, to be easily scaled out and managed with little administrative overhead. In exchange, the architecture requires applications to conform to certain rules and restrictions.
There are two fundamental parts to a Heroku application: Dynos, which follow the proccess model; and Add-ons, which are provided through third-party integrations.
The main unit of a Heroku application is the Dyno.
Dynos are ephemeral servers which run a single process. Each process started by a dyno must be assigned a “process type”. A dyno’s type is defined by the starting process type.
Even though a dyno can only start a single process, once started that process may spawn additional processes within the dyno within limits.
Keep in mind, dynos do not retain data. Data does not persist between Dyno restarts and there are no shared volumes between dynos. Practically speaking, you cannot retain any data on a dyno. Add-ons should be used for persistence and are explained below.
There are three types of Dynos tailored for different workloads: web dynos, worker dynos, and one-off dynos.
Only web dynos receive HTTP traffic via the Heroku router. Heroku assigns a single
$PORT environment variable to all dynos running a
web process type. All inbound HTTP traffic to a
web process goes through the single assigned
$PORT variable. The Heroku router attaches headers to HTTP requests to describe the original request as received by Heroku.
Web Dynos also have the following restrictions not discussed above:
- They allow 50 active requests per
web dyno with a 50 request queue.
- They must connect to the Heroku provided
$PORT environment variable within 60 seconds or the dyno will automatically be shut down.
Persistence and other functionality needed by applications which cannot be provided by Dynos are available through Add-ons. Many add-ons are integrated with Dynos through environment variables.
In addition to the process described above, Go applications can also be cross-compiled into a binary and deployed to Heroku through the use of a custom slug. Slugs are containers (similar to Docker images) which hold everything needed to run a program on Heroku’s infrastructure. To deploy a Go application this way, a slug needs to be created, published, and released on Heroku. Heroku has published an article specifically about deploying Go slugs.