
## Introduction

[Gin](https://github.com/gin-gonic/gin) is a web framework written in Go (Golang) that focuses primarily on performance and simplicity.

This guide explains how to deploy an application written using Gin to the Koyeb serverless platform using git-driven deployment. By using [Koyeb](https://www.koyeb.com) to deploy your app from a GitHub repository, each time you push code changes, your application will automatically be built and deployed, replacing the running instance once your new version is healthy.

Once your application is deployed, it will benefit from Koyeb native autoscaling, automatic HTTPS (SSL), auto-healing, and global load balancing across our edge network with zero configuration.

You can deploy and preview the example application from this guide by clicking the Deploy to Koyeb button below:

[![Deploy to Koyeb](/static/images/deploy/button.svg)](https://app.koyeb.com/deploy?name=go-gin-on-koyeb&type=git&builder=buildpack&repository=github.com/koyeb/example-go-gin&branch=main)

You can consult the [repository on GitHub](https://github.com/koyeb/example-go-gin) to find out more about the example application that this guide uses.

## Requirements

To successfully follow and complete this guide, you'll need:

- The Go programming language installed on your local computer
- A [Koyeb account](https://app.koyeb.com) to deploy and run the Go web API
- A [GitHub account](https://github.com/) to store your application code

## Steps

In this guide, we'll be writing and deploying a Go API on Koyeb with the following steps:

1. [Building a minimalist Go Gin application](#Building-a-minimalist-Go-Gin-application)
2. [Deploy the Go Gin application on Koyeb](#Deploy-the-Go-Gin-application-on-Koyeb)

## Building a minimalist Go Gin application

To get started, create a new directory on your local computer to build the example application:

```bash
mkdir ~/gin-demo
cd ~/gin-demo
```

Next, run the following command to create a `go.mod` file and track your code's dependencies:

```bash
go mod init example-go-gin
```

As you add dependencies, the `go.mod` file will list the versions your code depends on allowing you to keep your builds reproducible and giving you direct control over which module versions to use.

In your project folder, create a new file named `server.go` with the following content inside:

```go
package main

import (
  "fmt"
  "os"

  "github.com/gin-gonic/gin"
)

func main() {
  port := os.Getenv("PORT")

  if port == "" {
    port = "8000"
  }

  r := gin.Default()

  r.GET("/", func(c *gin.Context) {
    c.JSON(200, gin.H{
      "message": "Hello, world!",
    })
  })

  r.GET("/:name", func(c *gin.Context) {
    name := c.Param("name")

    c.JSON(200, gin.H{
      "message": fmt.Sprintf("Hello, %s!", name),
    })
  })

  r.Run(fmt.Sprintf(":%s", port))
}
```

The code above launches a Gin server listening on port 8000 by default (can be overridden by setting the `PORT` environment variable). It serves two API routes:

- `/` returning `{"message": "Hello, world!"}`
- `/:name` returning `{"message": "Hello, :name!"}` where `:name` is a parameter taken from the requested URL path. For example, `/john` will return "Hello, john!".

In your terminal, execute `go mod tidy` to add the missing modules required by our project and add `github.com/gin-gonic/gin` as a project dependency.

You can now run the application locally by running `go run server.go` and navigating to `http://localhost:8000` in your web browser.

## Deploy the Go Gin application on Koyeb

Next, initialize a new git repository on your local machine running:

```bash
git init
```

Download a basic `.gitignore` file for Go projects from GitHub by typing:

```bash
curl -L https://raw.githubusercontent.com/github/gitignore/main/Go.gitignore -o .gitignore
```

Next, create a [new repository on GitHub](https://github.com/new) to host your project code. In your project directory, add a new remote pointing to the GitHub repository:

```bash
git remote add origin git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_GITHUB_REPOSITORY>.git
```

**Note:** Be sure to substitute your own GitHub user and repository names in the above command.

Lastly, add the `server.go`, `go.mod`, `go.sum`, and `.gitignore` files to your repository, commit your changes, and push them to GitHub:

```bash
git add server.go go.mod go.sum .gitignore
git commit -m "Initial commit"
git push -u origin main
```

Now that your Gin application is available on GitHub, go to the **Overview** tab of the [Koyeb control panel](https://app.koyeb.com) and click **Create Web Service** to begin:

1. Select **GitHub** as the deployment method.
2. In the repositories list, select the repository containing your Gin application. Alternatively, you can deploy the [public example repository](https://github.com/koyeb/example-go-gin) by entering `https://github.com/koyeb/example-go-gin` in the **Public GitHub repository** field.
3. Choose a name for your App and Service, for example `go-gin-on-koyeb`, and click **Deploy**.

Your application will be cloned from GitHub, built and deployed. You can monitor the progress by viewing your Service's build and deployment logs. Once the deployment is complete, you can access your application by clicking the Public URL ending in `koyeb.app` on your Service's detail page in the control panel.

If you want to learn about how Koyeb automatically builds your Go Gin applications from git, make sure to read our documentation on [how we build from git](/docs/build-and-deploy/build-from-git).

## Conclusion

In this guide, we demonstrated how to deploy a Go Gin application on Koyeb using git. Each change you push to your repository will automatically trigger a new build and deployment on the Koyeb serverless platform. Your changes then go live as soon as the deployment passes all necessary health checks. In case of a failure during one of your deployments, your latest working deployment will continue to function to ensure your application is always up and running.

Questions or suggestions to improve this guide? Join us on the **[community platform](https://community.koyeb.com/)** to chat!


This tutorial explains how to deploy a Go Gin application on the Koyeb serverless platform using git-driven deployment.

Deploy a Go Gin Application on Koyeb


## Introduction

In this guide, we will explain how to build and deploy a Go API using the Gin framework on the Koyeb serverless platform.

[Gin](https://github.com/gin-gonic/gin) is a web framework written in Go focusing on performance. It provides an elegant way to write web applications and microservices and comes with a set of commonly used primitives like routing, middleware, rendering, and more.

By deploying your application on Koyeb, you benefit from powerful primitives including native autoscaling, automatic HTTPS (SSL), auto-healing, and global load-balancing across our edge network with zero configuration.

## Requirements

To successfully follow and complete this guide, you need:

- The Go programming language installed
- [Docker](https://docs.docker.com/get-docker/) installed on your machine
- A [Koyeb account](https://app.koyeb.com) to deploy and run the Go web API
- The [Koyeb CLI](/docs/cli/installation) installed to interact with Koyeb from the command line
- Have a registry that we will use to store our Go web app Docker image and deploy it on Koyeb

## Steps

To successfully complete this guide and deploy the Go API on Koyeb, you need to follow these steps:

1. [**Building the Go API using Gin**](#building-the-go-api-using-gin)
2. [**Dockerize the Go application**](#dockerize-the-go-application)
3. [**Deploy the Dockerized Go API on Koyeb**](#deploy-the-dockerized-go-api-on-koyeb)

## Building the Go API using Gin

First, let's get started by creating a new directory in your [GOPATH](https://golang.org/doc/gopath_code#GOPATH) to build our sample application:

```bash
mkdir $GOPATH/src/go-demo
cd $GOPATH/src/go-demo
```

In this guide, we name the directory `go-demo`. You can name the folder whatever you like.

Next, run `go mod init` to create a `go.mod` file and track your code's dependencies. As you add dependencies, the `go.mod` file will list the versions your code depends on allowing you to keep your builds reproducible and gives you direct control over which module versions to use.

In your project folder, create a new file named `server.go` with the following content inside:

```go
package main

import (
	"fmt"
	"os"

	"github.com/gin-gonic/gin"
)

func main() {
	port := os.Getenv("PORT")

	if port == "" {
		port = "8000"
	}

	r := gin.Default()

	r.GET("/", func(c *gin.Context) {
		c.JSON(200, gin.H{
			"message": "Hello, world!",
		})
	})

	r.GET("/:name", func(c *gin.Context) {
		name := c.Param("name")

		c.JSON(200, gin.H{
			"message": fmt.Sprintf("Hello, %s!", name),
		})
	})

	r.Run(fmt.Sprintf(":%s", port))
}
```

The code above launch a Gin server listening on port 8000 by default with two API routes configured:

- `/` returning "Hello, world!"
- `/:name` returning "Hello, :name!" where :name is the string passed in parameter, i.e /john will return "Hello, john!".

Then, in your terminal execute `go mod tidy` to add missing modules required by our project and add `github.com/gin-gonic/gin` as a project dependency.

You can now run the application locally running `go run server.go` and navigate in your browser at `http://localhost:8000`.

## Dockerize the Go application

To Dockerize our Go application, create a `Dockerfile` in your project directory.
In this guide, we use [Docker multi-stage build](https://docs.docker.com/develop/develop-images/multistage-build/) to keep the image layers size as small as possible and to ensure our image contains only what is needed to run.

In your Dockerfile, copy the content below:

```dockerfile
FROM golang:1.16-alpine AS builder
WORKDIR /app
COPY . .
RUN go mod download
RUN go build -o ./go-demo ./server.go


FROM alpine:latest AS runner
WORKDIR /app
COPY --from=builder /app/go-demo .
EXPOSE 8000
ENTRYPOINT ["./go-demo"]
```

The first stage is used to install dependencies and build our application, in the second one we copy the application binary from stage one and use it to run the application.

To build the Docker image execute the following command in your terminal:

```bash
docker build . -t <DOCKER_HUB_USERNAME>/go-demo
```

_In this guide we will push the Docker image to the Docker Hub. You are free to use another different registry as Koyeb allows you to deploy from any container registry._

Once the build is completed, you can run a container using the image locally to validate everything is working as expected running:

```bash
docker run -p 8000:8000 <DOCKER_HUB_USERNAME>/go-demo
```

If everything goes well, your container starts properly, you can test the routes using curl:

```bash
$curl localhost:8000/
Hello, world!
```

Next, we can push the Docker image to a container registry, in this guide, the Docker Hub using the following command:

```bash
docker push <DOCKER_HUB_USERNAME>/go-demo
```

On the push command is completed, the Docker image is stored on the container registry and we can deploy it on Koyeb.

## Deploy the Dockerized Go API on Koyeb

We are now ready to deploy our Go web application on Koyeb. First, create a Koyeb Secret to store your container registry configuration.
In this guide, we will deploy our app from the Docker Hub. For other container registries example, check out the related [documentation](/docs/apps/private-container-registry-secrets).

_Note: if your Docker image is public, there is no need to create a secret containing your container registry configuration._

```bash
echo \
'{
  "auths": {
    "index.docker.io/v1/": {
      "username": "<REPLACE_ME_WITH_DOCKER_HUB_USERNAME>",
      "password": "<REPLACE_ME_WITH_DOCKER_HUB_TOKEN>"
    }
  }
}' | koyeb secrets create docker-hub-credentials --value-from-stdin
```

We can now deploy the Go web application on Koyeb Serverless Platform running:

```bash
koyeb app init go-demo --docker "<REPLACE_ME_WITH_DOCKER_HUB_USERNAME>/go-demo" --ports 8000:http --routes /:8000 --docker-private-registry-secret docker-hub-credentials
```

This command creates a new Koyeb App and deploys our Go application exposing port 8000 and making it publicly accessible on the `/` route of your Koyeb App URL.

To retrieve your Koyeb App URL and access your application, run:

```bash
$koyeb app get go-demo
ID                                  	NAME           	DOMAINS                             	UPDATED AT
d58ebed1-48c0-46b7-a2f1-91f3ffdbccf2	go-demo        	go-demo-<YOUR_ORG>.koyeb.app	2021-06-23 09:46:55.411403 +0000 UTC
```

Open the URL in your browser to access your application running on Koyeb and natively offering autoscaling, automatic HTTPS (SSL), auto-healing, and global load-balancing across our edge network.


This guide explains how to build and deploy a RESTful Go API using the Gin framework on the Koyeb serverless platform.

Gin

Deploy a Go Gin Application on Koyeb

Deploy a RESTful Go API with Gin on Koyeb