Deploying a Simple Golang Web App on Heroku
A developer and DZone Core member gives an in-depth tutorial on how to create a web application using the Go language, the Gin web framework, and Heroku.
Join the DZone community and get the full member experience.Join For Free
The Go programming language, often referred to as "Golang," has gained a lot of well-deserved traction in the DevOps community. Many of the most popular tools such as Docker, Kubernetes, and Terraform are written in Go, but it can also be a great choice for building web applications and APIs.
Go provides you with all the speed and performance of a compiled language, but feels like coding in an interpreted language. This comes down to the great tooling that you get out of the box with a compiler, runner, test suite, and code formatter provided by default. Add to that the robust and easily comprehensible approach to concurrency, to take maximum advantage of today's multi-core or multi-CPU execution environments, and it's clear why the Go community has grown so rapidly.
Go feels like it was created with specific goals in mind, leading to a deceptively simple language design that's straightforward to learn, without compromising on capabilities.
In this post, I'm going to show you how easy it is to develop a simple web application in Go, package it as a lightweight Docker image, and deploy it to Heroku. I'll also show a fairly new feature of Go: built-in package management.
I'm going to use Go's built-in module support for this article.
Go 1.0 was released in March 2012. Up until version 1.11 (released in August 2018), developing Go applications involved managing a GOPATH for each "workspace," analogous to Java's
JAVA_HOME, and all of your Go source code and any third-party libraries were stored below the
Gemfile for Ruby,
I'm not saying you can't manage the
GOPATHenvironment variable to isolate projects from one another. I particularly find the package manager approach is easier.
Thankfully, Go now has excellent package management built in, so this is no longer a problem. However, you might find
GOPATH mentioned in many older blog posts and articles, which can be a little confusing.
Let's get started on our web application. As usual, this is going to be a very simple "Hello, World!" app, because I want to focus on the development and deployment process, and keep this article to a reasonable length.
- A recent version of Golang (I'm using 1.14.9.)
- A Heroku account (the free account works fine for this example.)
- The Heroku command-line client
Go mod init
To create our new project, we need to create a directory for it, and use the
go mod init command to initialize it as a Go module.
It's common practice to use your GitHub username to keep your project names globally unique, and avoid name conflicts with any of your project dependencies, but you can use any name you like.
You'll see a
go.mod file in the directory now. This is where Go will track any project dependencies. If you look at the contents of the file, they should look something like this:
Let's start committing our changes:
Create a file called
hello.go containing this code:
Let's break this down a little:
This creates a router object,
r, using the built-in defaults that come with Gin.
Then, we assign a handler function to be called for any HTTP GET requests to the path
/hello, and to return the string "Hello, World!" and a 200 (HTTP OK) status code:
Finally, we start our web server and tell it to listen on port 3000:
To run this code, execute:
You should see output like this:
Now if you visit
http://localhost:3000/hello in your web browser, you should see the message "Hello, World!"
Notice that we didn't have to install Gin separately, or even edit our
go.mod file to declare it as a dependency. Go figures that out and makes the necessary changes for us, which is what's happening when we see these lines in the output:
If you look at the
go.mod file, you'll see it now contains this:
You will also see a
go.sum file now. This is a text file containing references to the specific versions of all the package dependencies, and their dependencies, along with a cryptographic hash of the contents of that version of the relevant module.
go.sum file serves a similar function to
Gemfile.lock in a Ruby project, and you should always check it into version control along with your source code.
Let's do that now:
Serving HTML and JSON
I'm not going very far into what you can build with Gin, but I do want to demonstrate a little more of its functionality. In particular, sending JSON responses and serving static files.
Let's look at JSON responses first. Add the following code to your
hello.go file, right after the
Here we're creating a "group" of routes behind the path
/api with a single path
/ping which will return a JSON response.
With this code in place, run the server with
go run and then hit the new API endpoint:
You should get the response:
Finally, let's make our web server serve static files. Gin has an additional library for this.
Change the import block at the top of the
hello.go file to this:
The most popular code editors have Golang support packages you can install which will take care of the
importdeclarations for you automatically, updating them for you whenever you use a new module in your code.
Then, add this line inside the
The full code for our web application now looks like this:
r.Use(static.Serve... line enables our web server to serve any static files from the
views directory, so let's add a few:
Now restart the web server using
go run hello.go and visit
http://localhost:3000 and you should see the styled message:
We've written our Go web application, now let's package it up as a Docker image. We could create it as a Heroku buildpack, but one of the nice features of Go is that you can distribute your software as a single binary file. This is an area where Go really shines, and using a Docker-based Heroku deployment lets us take advantage of that. Also, this technique isn't limited to Go applications: you can use Docker-based deployment to Heroku for projects in any language. So, it's a good technique to understand.
So far, we've been running our code with the
go run command. To compile it into a single, executable binary, we simply run:
This will compile all our Go source code and create a single file. By default, the output file will be named according to the module name, so in our case it will be called
We can run this:
And we can hit the same HTTP endpoints as before, either with
curl or our web browser.
The static files are not compiled into the binary, so if you put the
helloworldfile in a different directory, it will not find the
viewsdirectory to serve our HTML and CSS content.
That's all we need to do to create a binary for whatever platform we're developing on (in my case, my Mac laptop). However, to run inside a Docker container (for eventual deployment to Heroku) we need to compile a binary for whatever architecture our Docker container will run on.
I'm going to use Alpine Linux, so let's build our binary on that OS. Create a
Dockerfile with the following content:
In this image, we start with the
golang base image, add our source code, and run
go build to create our
We can build our Docker image like this:
Don't forget the trailing
.at the end of that command. It tells Docker we want to use the current directory as the build context.
This creates a Docker image with our
helloworld binary in it, but it also contains all the Go tools needed to compile our code, and we don't want any of that in our final image for deployment, because it makes the image unnecessarily large. It can also be a security risk to install unnecessary executables on your Docker images.
We can see the size of our Docker image like this:
For comparison, the
alpine image (a lightweight Linux distribution, often used as a base for Docker images) is much smaller:
On my Mac, the
helloworld binary is around 14MB, so the Golang image is much bigger than it needs to be.
What we want to do is use this Dockerfile to build our
helloworld binary to run on Alpine Linux, then copy the compiled binary into an Alpine base image, without all the extra Golang tools.
We can do this using a "multistage" Docker build. Change the Dockerfile to look like this:
On the first line, we label our initial Docker image
Later, we switch to a different base image
FROM alpine and then copy the
helloworld binary from our builder image like this:
Build the new Docker image:
Now, it's the size you would expect for a base Alpine image plus our
We can run our web server from the Docker image like this. (If you have another version running using
go run hello.go or
./helloworld, you'll need to stop that one first, to free up port 3000.)
docker run --rm -p 3000:3000 helloworld
The dockerized webserver should behave just like the
go run hello.goand
./helloworldversions except that it has its own copies of the static files. So, if you change any of the files in
views/you won't see the changes until you rebuild the Docker image and restart the container.
Deploy to Heroku
Now that we have our dockerized web application, let's deploy it to Heroku. Heroku is a PaaS provider that makes it simple to deploy and host an application. You can set up and deploy your application through the Heroku UI, or through the Heroku CLI. For this example, we'll use the Heroku command-line application.
Getting PORT From an Environment Variable
We've hard-coded our web server to run on port 3000, but that won't work on Heroku. Instead, we need to alter it to run on whichever port number is specified in the
PORT environment variable, which Heroku will supply automatically.
To do this, alter the
r.Run line near the bottom of our
hello.go file, and remove the
":3000" string value so the line becomes:
The default behavior of Gin is to run on whatever port is in the
PORT environment variable (or port 8080 if nothing is specified). This is exactly the behavior Heroku needs.
Setting up Our Heroku app
First, log into Heroku:
Now, create an app:
Tell Heroku we want to build this project using a Dockerfile, rather than a buildpack:
To do this, we also need to create a
heroku.yml file like this:
heroku.yml file is a manifest that defines our app and allows us to specify add-ons and config vars to use during app provisioning.
Next, add git and commit these files, then push to Heroku to deploy:
My git configuration uses
mainas the default branch. If your default branch is called
master, then run
git push heroku masterinstead.
You should see Heroku building the image from your Dockerfile, and pushing it to the Heroku Docker registry. Once the command completes, you can view the deployed application in your browser by running:
To recap, here's a summary of what we covered today:
- Creating a Golang web application, using Go modules and the Gin web framework to serve strings, JSON, and static files.
- Using a multistage Dockerfile to create a lightweight Docker image.
- Deploying a Docker-based application to Heroku using
heroku stack:set containerand a
I've only scratched the surface in this article on how to use Go to build web applications and APIs. I hope this gives you enough to get started on your own Golang web applications.
Opinions expressed by DZone contributors are their own.