Deploying a Simple Go/Gin Application on Heroku

The speed and efficiency of the Go programming language make it popular for backend development. Combine Go with the Gin framework—which offers a fast and minimalistic approach to building web applications—and developers can easily create high-performance APIs and web services. Whether you’re working on a personal project or building a production-ready application, Go and Gin make for an attractive stack perfectly suited for lightweight, scalable web development.

Creating a Go/Gin application might seem straightforward: You write a few routes, connect a database, and spin up a local server. But when it comes to deploying your app, things can get tricky. Developers unfamiliar with cloud deployment often struggle with configuring environment variables, managing dependencies, and ensuring their app runs smoothly on a hosting platform.

Fortunately, Heroku makes this process incredibly simple. With its streamlined deployment workflow and built-in support for Go, Heroku lets you deploy your Go/Gin app with minimal configuration.

In this article, we’ll walk through the process of building and deploying a Go/Gin web application on Heroku. We’ll set up a local development environment, prepare an application for deployment, and deploy it to run on Heroku. Along the way, we’ll cover best practices and troubleshooting tips to ensure a smooth deployment.

By the end of this guide, you’ll have a fully functional Go/Gin application running on Heroku—and you’ll gain the knowledge needed to deploy future projects with confidence. Let’s get started!

Setting up your development environment

To get started, you must set up your development environment. Here are the steps to install what you need and test your application locally.

An example project can be found in this GitHub repository.

Download and install Go

Download the Go installer from the official Go website, making sure you choose the correct operating system. For Windows or Linux, follow the respective installation instructions on the website.

If you’re on macOS, you can use Homebrew:

$ brew install go

Once installed, verify your installation by running:

$ go version

You should see your Go version printed in the terminal. For this guide, we’re running version 1.24.0.

Set up your workspace

Create a new directory for your project and initialize a Go module. Open your terminal and execute:

~/project$ go mod init github.com/YOUR-USERNAME/YOUR-REPO-NAME

This neatly organizes your project and its dependencies, ensuring everything is in order. In the examples to follow YOUR-REPO-NAME will be go-gin.

Add the Gin framework

Now it’s time to invite Gin to the party. Gin is a high-performance web framework that will help you build your REST server fast.

Run the following command to add Gin to your project:

~/project$ go get github.com/gin-gonic/gin

This fetches the Gin package and its dependencies.

The server application code goes in a file called main.go. Download that code here.

Finally, run the server:

~/project$ go run main.go

Test your application locally

Before declaring your quest a success, make sure your application runs smoothly on your local machine. As you run the server as described above, you’ll see output indicating that it’s up and running.

~/project$ go run main.go

[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.

[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:	export GIN_MODE=release
 - using code:	gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /quotes                   --> main.main.func1 (3 handlers)
[GIN-debug] GET    /quote                    --> main.main.func2 (3 handlers)
[GIN-debug] POST   /quote                    --> main.main.func3 (3 handlers)
[GIN-debug] [WARNING] You trusted all proxies, this is NOT safe. We recommend you to set a value.
Please check https://pkg.go.dev/github.com/gin-gonic/gin#readme-don-t-trust-all-proxies for details.
[GIN-debug] Listening and serving HTTP on :8080

Test your API server endpoints by sending a curl request in a separate terminal window. For example:

$ curl -s -X GET http://localhost:8080/quote | jq
{
  "quote": "The journey of a thousand miles begins with a single step."
}

(We use jq to pretty-print the JSON result.)

Creating a Heroku App

Assuming you have installed the Heroku CLI, you can create a new Heroku app. Run the following commands:

~/project$ heroku login

~/project$ heroku apps:create my-go-gin-api

Creating ⬢ my-go-gin-api... done
https://my-go-gin-api-7f40e19ce771.herokuapp.com/ | https://git.heroku.com/my-go-gin-api.git

This creates your Heroku app, accessible at the app URL (in the above example, that’s https://my-go-gin-api-7f40e19ce771.herokuapp.com/). The command also creates a Git remote so you can push your code repo to Heroku with a single command.

~/project$ git remote show heroku

* remote heroku
  Fetch URL: https://git.heroku.com/my-go-gin-api.git
  Push  URL: https://git.heroku.com/my-go-gin-api.git

You’ll also see your newly created app in your Heroku Dashboard. Clicking the Open app button will take you to your app URL.

Create the Procfile

The Procfile tells Heroku how to run your application. In your project’s root directory, create a file named Procfile (without any extension). For most simple Go applications, your Procfile will consist of a single line, like this:

web: go run main.go

This tells Heroku that your app will be a web process, and Heroku should start the process by running the command go run main.go. Simple enough! Add the file to your repository.

Tidy up your Go project

Finally, use the following command to clean up your go.mod file to ensure all dependencies are properly listed:

$ go mod tidy

Ensure your go.mod and go.sum files have also been added to your repository. This allows Heroku to automatically download and manage dependencies during deployment with the Procfile.

Deploying your application

After completing these simple preparation steps, you’re ready to push your project to Heroku. Commit your changes. Then, push them to your Heroku remote.

~/project$ git add .
~/project$ git commit -m "Prepare app for Heroku deployment"
~/project$ git push heroku main

The git push command will set off a flurry of activity in your terminal, as Heroku begins building your application in preparation to run it:

…
Writing objects: 100% (26/26), 9.52 KiB | 9.52 MiB/s, done.
…
remote: Building source:
remote:
remote: -----> Building on the Heroku-24 stack
remote: -----> Determining which buildpack to use for this app
remote: -----> Go app detected
remote: -----> Fetching jq... done
remote: -----> Fetching stdlib.sh.v8... done
remote: ----->
remote:        Detected go modules via go.mod
remote: ----->
remote:        Detected Module Name: github.com/your-username/go-gin
remote: ----->
remote: -----> New Go Version, clearing old cache
remote: -----> Installing go1.24.0
remote: -----> Fetching go1.24.0.linux-amd64.tar.gz... done
remote: -----> Determining packages to install
remote: go: downloading github.com/gin-gonic/gin v1.10.0
…
remote:        
remote:        Installed the following binaries:
remote:        		./bin/go-gin
remote: -----> Discovering process types
remote:        Procfile declares types -> web
remote: 
remote: -----> Compressing...
remote:        Done: 6.6M
remote: -----> Launching...
remote:        Released v3
remote:        https://my-go-gin-api-7f40e19ce771.herokuapp.com/ deployed to Heroku
remote: 
remote: Verifying deploy... done.
To https://git.heroku.com/my-go-gin-api.git
 * [new branch]      main -> main

This output tells you the location of the binary that Heroku built during the deploy process. In this case, it is at: ./bin/go-gin. For some Go applications, if you have trouble reaching your service and see errors in the logs, you might need to edit your Procfile to have Heroku run the binary directly, rather than using go directly with the source file. For example, your modified Procfile might look like this:

web: ./bin/go-gin

Test the live application

With your Go application running on Heroku, you can test it by sending a curl request to your Heroku app URL. For example:

$ curl -s \
    -X GET https://my-go-gin-api-7f40e19ce771.herokuapp.com/quote | jq

{
  "quote": "This too shall pass."
}

To ensure everything is running smoothly after deployment, you can the following command to tail the server’s live logs:

~/project$ heroku logs --tail

…
2025-02-25T15:11:01.922123+00:00 heroku[web.1]: State changed from starting to up
2025-02-25T15:11:22.000000+00:00 app[api]: Build succeeded
2025-02-25T15:16:31.411009+00:00 app[web.1]: [GIN] 2025/02/25 - 15:16:31 | 200 |      29.199µs |   174.17.39.113 | GET      "/quote"
2025-02-25T15:16:31.411487+00:00 heroku[router]: at=info method=GET path="/quote" host=my-go-gin-api-7f40e19ce771.herokuapp.com request_id=7df071ec-9841-499f-b584-61574920e9df fwd="174.17.39.113" dyno=web.1 connect=0ms service=0ms status=200 bytes=186 protocol=https

It’s time for you to Go!

In this article, we walked through each step of creating your Go application that uses the Gin framework, from project setup to Heroku deployment. You can see the power and simplicity of combining Gin’s robust routing capabilities with Heroku’s flexible, cloud-based platform. On top of this, it’s easy to scale your applications as your needs evolve.

Explore the additional features both Heroku and Gin offer. Heroku’s extensive add-on ecosystem can boost your application’s functionality. You can also tap into advanced Gin middleware to optimize performance and strengthen security. To learn more, check out the following resources:

• Getting Started on Heroku with Go
• Heroku Go Support
• Heroku Go Buildpacks
  • Cedar generation (classic)
  • Fir generation (cloud native)
• Heroku Add-ons
• The Gin Web Framework
• External middleware for use with Gin