Run a Ruby App

Deploying a Ruby application on requires two essential ingredients: a Gemfile and a file. Full-stack frameworks like Rails, Padrino, and Hanami provide both of these for you. Micro-frameworks like Sinatra, Camping, and Rack itself require you to create your own.


If you don't have a gemfile, the best way to get started is to run:

bundle init

Once this file is created, proceed to add gems needed by your application, for example:

bundle add rackup

The Gemfile needs to include the framework you may be using, so if you are using, for example, Sinatra or Camping, add that gem too.

Finally add a web server, like puma, thin, or falcon. If you are not sure what web server to use, puma is a safe bet:

bundle add puma

The most basic file would be the following:

run do |env|
  [200, {}, ["Hello World"]]

Phusion Passenger guides provide a helpful list of starter files for various Ruby web frameworks.

We're now ready to run the app locally.

Running the Application

Run bundle exec rackup to start the application

bundle exec rackup
Puma starting in single mode...
* Puma version: 6.1.1 (ruby 3.2.1-p31) ("The Way Up")
*  Min threads: 0
*  Max threads: 5
*  Environment: development
*          PID: 26873
* Listening on
* Listening on http://[::1]:9292
Use Ctrl-C to stop

If you see a message suggesting that you need to run bundle binstub rack, that message can be safely ignored.

And connect to localhost:9292 to confirm that you have a working Ruby application. Now to package it up for Fly.

Install Flyctl and Login

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 log in to Fly.

Launch the App on Fly

To launch an app on fly, run flyctl launch in the directory with your source code. This will create and configure a fly app for you by inspecting your source code, then prompt you to deploy.

flyctl launch
Creating app in /Users/rubys/tmp/snapshot
Scanning source code
Detected a Ruby app
? Choose an app name (leave blank to generate one): 
? Select Organization: Sam Ruby (personal)
Some regions require a paid plan (fra, maa).
See to set up a plan.

? Choose a region for deployment: Ashburn, Virginia (US) (iad)
Created app 'late-bird-1771' in organization 'personal'
Admin URL:
? Would you like to set up a Postgresql database now? No
? Would you like to set up an Upstash Redis database now? No
Wrote config file fly.toml

Your Ruby app is prepared for deployment.

If you need custom packages installed, or have problems with your deployment
build, you may need to edit the Dockerfile for app-specific changes. If you
need help, please post on

Now: run 'fly deploy' to deploy your Ruby app.

First, this command scans your source code to determine if it meets the requirements for a deployable Ruby app.

After your source code is scanned and the results are printed, you'll be prompted for an organization. Organizations are a way of sharing application and resources between Fly users. Every fly account has a personal organization, called personal, which is only visible to your account. Let's select that for this guide.

Next, you'll be prompted to select a region to deploy in. The closest region to you is selected by default. You can use this or change to another region.

Finally you will be given the option to start a Postgres and/or a Redis database. If you need one or both, it is convenient to set them up now. Otherwise you can always add them later.

At this point, flyctl creates an app for you and writes your configuration to a fly.toml file. You'll then be prompted to build and deploy your app. Once complete, your app will be running on fly.

Config First!

Most Dockerfiles expect some configuration settings through ENV. The generated fly.toml file has a place for you to add your custom ENV settings. It's the [env] block.

  MY_SPECIAL_ENV = "some_value"

Add whatever values your Dockerfile or container requires.

Sometimes you have secrets that shouldn't be checked in to git or shared publicly. For those settings, you can set them using fly secrets.

fly secrets set MY_SECRET=romance
Secrets are staged for the first deployment

You can list the secrets you've already set using fly secrets list

fly secrets list
NAME      DIGEST                           DATE
MY_SECRET b9e37b7b239ee4aefc75352fe3fa6dc6 1m20s ago

The values aren't displayed since they are secret!

Deploying to Fly

To deploy changes to your app, just run just run:

fly deploy

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

Connecting to the App

The quickest way to browse your newly deployed application is with the flyctl open command.

fly open

Your browser will be sent to the displayed URL. Fly will auto-upgrade this URL to a HTTPS secured URL.

Arrived at Destination

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

You can monitor and explore your app with the following command:

fly dashboard