Go is an open-source programming language, backed by Google, that makes it easy to build simple, reliable, and efficient software. Go is gaining popularity because it was built for developing distributed systems that C and Java have limitations around. Go’s efficiency with network servers and its friendly syntax makes it a great choice for developing networked applications.
In this tutorial, I will demonstrate how to deploy a demo Go application to Heroku. You ready? Let’s dig in.
Prerequisites
To follow this tutorial, a few things are required:
- Basic knowledge of programming
- Go installed on your system (you can find an installation guide here)
- An account on Heroku
- A CircleCI account
- A GitHub account
With all these installed and set up, let’s begin the tutorial.
Building a simple API with Go
Let’s begin by creating a very simple mock API with two endpoints. One endpoint for the API root, /
, and another endpoint, /register
, that receives some user data, and echoes it back in a success response formatted in json
.
We will be creating this API using Go and Gin. Gin is a standard web framework for Go similar to Express.js for Node.js or Django for Python.
In a preferred location on your system, create a folder with the name go-registration-api
and navigate to the root of the folder:
mkdir go-registration-api
cd go-registration-api
Next, initialize the Go project by running the following:
go mod init go-registration-api
The go mode init
command is similar to npm init
in Node.js. It initializes the folder as a Go project named go-registration-api
. This command also creates a go.mod
file at the root of the project. This file is similar to package.json
file in Node.js. It manages dependencies and many more project-level configurations.
Let’s create our project entry file. At the root of the project, create the entry file named main.go
and paste in the following code:
package main
import "fmt"
func main (){
fmt.Println("It's Aliveeee!!!")
}
This is a simple “Hello World” Go application where we yell “It’s Aliveeee!!!” to the screen, waking up Frankenstein’s monster.
To run our code, head over to your Terminal. At the root of the project, run the following command:
go run main.go
In the above code, we call Go’s run
command, and supply it with the file we want to run. This will compile and run the code. It's Aliveeee!!!
is printed on the CLI.
For convenience, we don’t want to have to run go run main.go
each time we choose to run our application, so we need to create a makefile
file. Create a file named makefile
at the root of the project (no file extension). This file will help us proxy some of our commonly used Go
CLI commands with simpler ones. Enter the following into the makefile
:
dev:
go run main.go
Note: Makefiles only work with tabs. The second line above is tabbed once.
Here, we have created a proxy dev
command for go run main.go
. Now we can run the following:
make dev
This will give us the same result as running go run main.go
. It serves as our command for running the Go project in development mode.
Building the API
Now we can begin building our mock API. First, install the Gin framework by running the following command:
go get -u github.com/gin-gonic/gin
This downloads all the packages required for operating with Gin. A go.sum
file is created at the root of the project. This file works like the package-lock.json
in Node.js. It keeps track of the exact version of all the packages being installed in the project.
Once Gin is installed, replace all the code in main.go
:
package main
import "github.com/gin-gonic/gin"
func main() {
r := gin.Default()
r.GET("/", func(c *gin.Context) {
c.JSON(200, gin.H{
"message": "Welcome to the Go Registration API",
})
})
r.POST("/register", func(c *gin.Context) {
fullname := c.PostForm("fullname")
phone := c.PostForm("phone")
email := c.PostForm("email")
c.JSON(200, gin.H{
"status": "success",
"message": "User details successfully posted",
"fullname": fullname,
"phone": phone,
"email": email,
})
})
r.Run()
}
In the code above, we start by importing the gin
package. Then, in our main
function, we created a new gin
with the following line.
r := gin.Default()
This command returns a router that includes helpful middleware for tasks like logging and recovery. Next, we created two endpoints:
/
: AGET
endpoint that returns ajson
object with a message welcoming the user to the API/register
: APOST
endpoint that receives a user’s form data, and echoes it back in ajson
success response
Finally, we call r.Run()
to make sure that the application doesn’t exit, but keeps running.
Running the API endpoints
Time to take our mock API for a spin. Run the application by typing the following command:
make dev
This will boot up a local server to serve the application at http://localhost:8080
.
Note: If the application was running while you were making the changes, shut down the app with Ctrl + C
and restart it.
Using Postman to call the endpoints results in the following two screenshots.
Setting up a Heroku app for deployment
We need a hosting service to deploy our Go application; I chose Heroku for this tutorial. Set up a Heroku application by navigating to the Heroku dashboard and clicking New. Select Create new app and fill in the application name.
After creating the application successfully, you will be redirected to the application page. Remember your application name, in this case go-registration-api
, as you will be needing it later on.
Find your Heroku API key, located on your Account Settings
page. You can access Account Settings from the dropdown menu that appears when you click your avatar at the top right of the webpage.
Connecting the project to CircleCI
Now that we have Heroku set up, we need to automate the deployment of our Go application. Begin by pushing your project to GitHub.
Next, go to the Add Projects page on the CircleCI dashboard.
Click Set Up Project.
On the set-up page, click Use Existing Config to instruct CircleCI that we are adding a configuration file manually, not using the sample displayed. Next, you get a prompt to either download a configuration file for the pipeline or start building.
Click Start Building. This build will fail because we have not set up our configuration file yet.
Next, we need to set up environment variables for the project we just added. This provides our project with authenticated access to Heroku for deployments.
Click Project Settings on the Pipelines page. Make sure your project is currently selected.
On the Project Settings page, click Environment Variables on the side menu.
On the Environment Variables page, click Add Environment Variable. Add these variables:
HEROKU_APP_NAME
: In this case,go-registration-api
is the name of your Heroku applicationHEROKU_API_KEY
: Find your Heroku account API key on the Account tab
Success! You have completed set up on your CircleCI console for deployment to Heroku.
Configuring automated deployment with CircleCI orbs
Now it is time to get our Go application deployed, and make it truly “Aliveeee!!!”. First, we need to create a Procfile
file at the root of the project.
Create the Procfile
file (with no file extension), and add the following command to the file:
web: bin/go-registration-api
Heroku runs the built version of our Go application, located in the bin
directory.
Next, create a deployment pipeline configuration file to contain our configuration script. At the root of the project, create a folder named .circleci
. Create a config.yml
file within that folder. Inside the config.yml
file, enter the following configuration:
version: 2.1
orbs:
heroku: circleci/heroku@0.0.10
workflows:
heroku_deploy:
jobs:
- heroku/deploy-via-git
We can deploy our application with only seven lines of code because we are using the power of CircleCI orbs. The configuration pulls in CircleCI’s Heroku orb. This orb abstracts a lot of boilerplate Heroku CLI commands, and provides an easy-to-use API for deploying applications.
Next, we call the heroku/deploy-via-git
job. This job checks out our code from the remote repository and deploys it to Heroku. It authenticates with Heroku using the environment variables we defined earlier.
Commit the changes to your project, and push to the remote repository to run the deployment script.
Click the SUCCESS label to view the details of the deployment.
The status details are logged to show how Heroku detects the app as a Go application, installs dependencies, builds the project, and runs the command in our Procfile
file.
Go to our application at https://go-registration-api.herokuapp.com
.
We can also test our /register
endpoint on the live application using Postman.
Conclusion
Go is an option for developers who love the fancy features of newer languages and frameworks, but want the power and enterprise-grade features of C, Java, and C++. If you are bored or frustrated with Node.js, Python, and Ruby, why not give Go a try?
Happy coding!
Fikayo Adepoju is a LinkedIn Learning (Lynda.com) Author, Full-stack developer, technical writer, and tech content creator proficient in Web and Mobile technologies and DevOps with over 10 years experience developing scalable distributed applications. With over 40 articles written for CircleCI, Twilio, Auth0, and The New Stack blogs, and also on his personal Medium page, he loves to share his knowledge to as many developers as would benefit from it. You can also check out his video courses on Udemy.