Build, Deploy And Run A Go Application

In our Hands-On section, we show how to deploy a deployable image file using Flyctl. The question we are going to answer here is how do we do that from the original source. In this Getting Started article, we look at how to deploy a Go application on Fly.

The Hellofly Application

You can get the code for the example from the hellofly Github repository. Just git clone https://github.com/fly-examples/hellofly to get a local copy.

The hellofly application is, as you'd expect for an example, small. It's a Go application that uses the gin web framework. Here's all the code form main.go:

package main

import (
        "net/http"
        "strings"

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

func main() {
        r := gin.Default()
        r.LoadHTMLGlob("./resources/templates/*")

        r.GET("/", handleIndex)
        r.GET("/:name", handleIndex)
        r.Run(":8080")
}

func handleIndex(c *gin.Context) {
        name := c.Param("name")
        if name != "" {
                name = strings.TrimPrefix(c.Param("name"), "/")
        }
        c.HTML(http.StatusOK, "hellofly.tmpl", gin.H{"Name": name})
}

The main function sets up the server after loading in templates for pages to be output. Those templates live in ./resources/templates/. When a request comes in, the handleIndex function looks for a name and feeds that name to a template. The template itself, hellofly.tmpl, is very simple too:

<!DOCTYPE html>
<html lang="en">
<head>
</head>
<body>
<h1>Hello from Fly</h1>
{{ if .Name }}
<h2>and hello to {{.Name}}</h2>
{{end}}
</body>
</html>

We're using a template as it makes it easier to show what you should do with assets that aren't the actual application.

Building the Application

As with most Go applications a simple go build will create a hellofly binary which we can run. It'll default to using port 8080 and you can view it on localhost:8080 with your browser. So, the raw application works. Now to package it up for Fly.

We are ready to start working with Fly and that means we need flyctl, our CLI app for managing apps on Fly. If you've already installed it, carry on. If not, hop over to our installation guide. Once thats installed you'll want to login to Fly.

Configure the App for Fly

Each Fly application needs a fly.toml file to tell the system how we'd like to deploy it. That file can be automatically generated with the command flyctl init command.

flyctl init

? App Name (leave blank to use an auto-generated name) hellofly

? Select organization: Dj (dj)

? Select builder: go
    Go Builtin
? Select Internal Port: 8080

New app created
  Name     = hellofly
  Owner    = demo
  Version  = 0
  Status   =
  Hostname = <empty>

Wrote config file fly.toml

You'll be asked for an application name first. We recommend that you go with the autogenerated names for apps to avoid namespace collisions. We're using hellofly here so you can easily spot it in configuration files.

Next you'll be prompted for an organization. Organizations are a way of sharing applications between Fly users. When you are asked to select an organization, there should be one with your account name; this is your personal organization. Select that.

Flyctl also asks you to select a builder. Builders are responsible for constructing the Docker image of your application which is then deployed to Fly's Firecracker VMs. The simplest to use are the builtin builders, which we recommend you use here. Select Go (Go Builtin). If you want to know more about the various builders, see Builders and Fly.

The last thing you will be asked for an internal port value. This is the port your application communicates over. If set incorrectly, Fly will be unable to connect to the application and it will fail health checks and be terminated. The default shown, 8080, is correct for the builtin builders which, by design, get applications to talk on port 8080. So, hit return and carry on.

One thing to know about the builtin Go builder is that it will automatically copy over the contents of the resources directory to the deployable image. This is how you can move static assets such as templates and other files to your application.

Inside `fly.toml`

The fly.toml file now contains a default configuration for deploying your app. In the process of creating that file, flyctl has also created a Fly-side application slot of the same name, "hellofly". If we look at the fly.toml file we can see the name in there:

app = "hellofly"

[build]
  builtin = "go"

[[services]]
  internal_port = 8080
  protocol = "tcp"

  [services.concurrency]
    hard_limit = 25
    soft_limit = 20

  [[services.ports]]
    handlers = ["http"]
    port = "80"

  [[services.ports]]
    handlers = ["tls", "http"]
    port = "443"

  [[services.tcp_checks]]
    interval = 10000
    timeout = 2000

The flyctl command will always refer to this file in the current directory if it exists, specifically for the app name value at the start. That name will be used to identify the application to the Fly service. The rest of the file contains settings to be applied to the application when it deploys.

We'll have more details about these properties as we progress, but for now, it's enough to say that they mostly configure which ports the application will be visible on.

Deploying to Fly

We are now ready to deploy our containerized app to the Fly platform. At the command line, just run:

flyctl deploy

This will lookup our fly.toml file, and get the app name hellofly from there. Then flyctl will start the process of deploying our application to the Fly platform. Flyctl will return you to the command line when it's done.

Viewing the Deployed App

Now the application has been deployed, let's find out more about its deployment. The command flyctl status will give you all the essential details.

flyctl status

App
  Name     = hellofly
  Owner    = demo
  Version  = 0
  Status   = running
  Hostname = hellofly.fly.dev

Allocations
ID       VERSION REGION DESIRED STATUS  HEALTH CHECKS      RESTARTS CREATED
0ac9ed79 0       fra    run     running 1 total, 1 passing 0        44s ago
$

As you can see, the application has been with a DNS hostname of hellofly.fly.dev, and an instance is running in Frankfurt. Your deployment's name will, of course, be different.

Connecting to the App

The quickest way to connect to your deployed app is with the flyctl open command. This will open a browser on the HTTP version of the site. That will automatically be upgraded to an HTTPS secured connection (for the fly.dev domain).

to connect to it securely. Add /name to flyctl open and it'll be appended to the URL as the path and you'll get an extra greeting from the hellofly application.

Bonus Points

If you want to know what IP addresses the app is using, try flyctl ips list:

flyctl ips list

TYPE ADDRESS                              CREATED AT
v4   50.31.246.73                         23m42s ago
v6   2a09:8280:1:3949:7ac8:fe55:d8ad:6b6f 23m42s ago

Arrived at Destination

You have successfully built, deployed, and connected to your first Go application on Fly.