Deploy a Fly app

Table of contents

• Install flyctl and login
• Prep an application for deploy
  • Register a new Fly app
    • Config file: fly.toml
  • Building and packaging
• Deploying an app
  • 📦 Package application
  • 🚢 Push app package to Fly
  • 📍 Register Services
  • 🚀 Release app package
• Using a Fly app
  • The info command
  • SSL certificates
  • App config
  • Network services

Install flyctl and login

We have a CLI tool for deploying and managing Fly applications. If you're on a Mac, you can install the CLI with Homebrew:

brew install superfly/tap/flyctl

For other operating systems, use the install script:

curl https://get.fly.io/flyctl.sh | sh

Once installed, log in to Fly with flyctl auth login:

flyctl auth login

Opening browser to url https://fly.io/app/auth/cli/token
Waiting for session...⣽ 

This will open a browser window you can use to register and authenticate with Fly.

Prep an application for deploy

The CLI operates in a working directory, so go ahead and change to your application directory — we'll use fly-example for this guide. If you want to try with a prebuilt application, you can clone one from our getting started repository:

git clone https://github.com/superfly/go-example.git fly-example
cd fly-example

Register a new Fly app

The flyctl apps create command creates all the necessary infrastructure to deploy your application, and then writes a fly.toml file to your working directory.

flyctl apps create

? App Name (leave blank to use an auto-generated name) 
? Select organization: Fly (fly)
New app created
  Name     = dark-pine-485 
  Owner    = fly             
  Version  = 0               
  Status   =                 
  Hostname = 

Wrote config file fly.toml

Config file: fly.toml

The fly.toml config file specifies the application name so flyctl knows which application to operate on when you run commands. It also specifies services, which determine which ports to listen on and what "handlers" (if any) to apply before proxying to your application.

cat fly.toml

app = "dark-pine-4852"

[[services]]
  internal_port = 8080
  protocol = "TCP"
  [services.port.80]
    handlers = ["HTTP"]
  [services.port.443]
    handlers = ["TLS", "HTTP"]

By default, new apps listen for HTTP connections on port 80 and HTTPS connections on port 443, and forward requests on to application port 8080. This is all configurable, though, you can configure your application services to handle almost any kind of TCP traffic.

Building and packaging

Fly apps are built using app builders, or from a raw Dockerfile. Builds get packaged into a Docker Image (we don't actually run Docker, but it's a reasonable packaging format with good tooling).

The build section of the Fly config specifies build instructions. The optional builder setting defines an app specific builder, and builders may have their own settings:

[build]
  builder = "github.com/superfly/builders//deno"

If no builder is specified, flyctl will attempt to build the Dockerfile in the working directory.

Deploying an app

The flyctl deploy command triggers a sequence of actions: package -> push -> network setup -> release.

flyctl deploy

📦 Package application

App config file '/home/kurt/fly-example/fly.toml'
Deploy source directory '/home/kurt/fly-example'
Docker daemon available, performing local build...
Using Dockerfile from project: /home/kurt/fly-example/Dockerfile
...
Successfully built ccffce94bd6e
Successfully tagged registry.fly.io/dark-pine-4852:deployment-1569524269
Image size: 14 MB

🚢 Push app package to Fly

==> Pushing image
The push refers to repository [registry.fly.io/dark-pine-4852]
--> done

📍 Register Services

==> Registering Services
  TCP 80 --> TCP 8080 (handlers: HTTP)
  TCP 443 --> TCP 8080 (handlers: TLS HTTP)

🚀 Release app package

==> Deploying Image
--> done
  Version     = v0                
  Reason      = Deploy image      
  Description =                   
  User        = dev@fly.local 
  Date        = 1s ago            

Using a Fly app

Each app gets a .dev hostname and IP addresses you can use to connect. The flyctl info command shows lots of information about an app that deploys successfully:

The info command

flyctl info

App
  Name     = dark-pine-4852                  
  Owner    = fly                             
  Version  = 0                               
  Status   = running                         
  Hostname = https://dark-pine-4852.fly.dev

Services
  TASK   PROTOCOL   PORT   INTERNAL PORT   HANDLERS  
  app    tcp        80     8080            http      
  app    tcp        443    8080            tls http  

IP Addresses
  ADDRESS                                TYPE  
  77.83.140.117                          v4    
  2a09:8280:1:f898:2460:35d0:b918:1550   v6

SSL certificates

Apps using the TLS service handler can use an unlimited number of Fly managed certificates. Use the flyctl certs command to add, list, and remove certificates.

App config

You can add configuration options and application secrets (like DB credentials) using the flyctl secrets command. We inject these into your application process as environment variables. Read more about app configuration →

Network services

By default, applications listen for HTTP traffic on port 80 and HTTPS traffic on port 443. This is configurable, you can build apps that expose gRPC services, for example, or any other service that works over TCP. Read more about global service routing →