@fly/fly

Fly

The Fly runtime is an open source Javascript environment built to run Edge Applications. It gives developers powerful caching, content modification, and routing tools.

The runtime is based on v8, with a proxy-appropriate set of Javascript libraries. There are built in APIs for manipulating HTML and Image content, low level caching, and HTTP requests/responses. When possible, we use WhatWG standards (like fetch, Request, Response, Cache, ReadableStream).

You can use it locally for development and testing, and deploy it to Fly's fleet of edge servers for production use.

Edge Applications: the in between

You can use Fly to build HTTP load balancers, caching services, etc, etc. Edge Applications are typically built to replace or augment infrastructure that runs between web apps and users.

This in-between is a great place to solve certain categories of problems. If you need to solve one of these, you might want to build an Edge Application:

• A/B testing at the load balancer layer
• Route traffic to different cloud providers
• Cache personalization data geographically close to individual users
• Route authenticated users to specific apps
• Enforce backend SLAs, serve fallback content when backends are degraded
• Load balancers across cloud storage providers
• Per user rate limiting (for APIs or apps)

Installation

macOS

Homebrew is the quickest way to get started on macOS:

brew tap superfly/brew && brew install superfly/brew/fly

Linux

Use the standalone installer

Windows

Use npm

Other installation methods

Standalone Install

The standalone install is a tarball containing the Fly CLI, precompiled native extensions, and a nodejs binary. This is useful in containers or hosts with restricted access.

To quickly install into /usr/local/lib/fly and /usr/local/bin/fly, run this script (requires sudo and not Windows compatible):

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

Otherwise, download one of the tarballs below and extract it yourself.

Tarballs

• macOS
• Linux (x64)

npm

The Fly CLI and runtime is built on Node.js with native extensions. As a result, installing from npm requires a proper C/C++ compiler toolchain and takes significantly longer than the other methods. If you're on Windows or don't have XCode/gcc installed, follow the node-gyp instructions before continuing.

Install globally:

npm install -g @fly/fly

or as a devDependency in your project:

npm install --save-dev @fly/fly

Usage

Hello World!

Write javascript code to a file (index.js):

fly.http.respondWith((request) => {
  return new Response("Hello! We support whirled peas.", { status: 200})
})
// if you'd prefer to be service worker compatible, this is also supported:
// around addEventListener('fetch', function(event){})

Start the fly server:

fly server

Visit your app:

open http://localhost:3000

Change code and configuration, it's reloaded seamlessly.

How does it work?

Simply put:

• Uses a basic webpack configuration to bundle your javascript
• Assumes the presence of index.js or index.ts
• You can customize everything by creating a webpack.fly.config.js which will be loaded for you
• Use npm packages compatible with the v8 javascript engine, you don't have access to node.js-specific concepts or packages.

Configuration

By default, fly will read your .fly.yml file in your current working directory.

# .fly.yml
app: my-app-name
config:
  foo: bar
files:
  - path/to/file

Properties:

• app - the fly.io app name, can be ommitted, useful for deployment purposes
• config - arbitrary settings for your applications, accessible in your code via the global variable app.config
• files - array of files, relative to your .fly.yml to include in the deployment. Can be accessed via fetch("file://path/to/file")

Secrets

You can require secrets in your app.config like this:

# .fly.yml
app: my-app-name
config:
  secretThing:
    fromSecret: secretKey

In your code, you can seamlessly use this value like:

app.config.secretThing

When deployed on fly.io, secrets are fetched from an encrypted store. You need to pre-define your secrets via fly secrets:set <key> <value>.

Locally, you need to define them in a .fly.secrets.yml file, make sure you add it to your .gitignore as it can contain sensitive data. Example file.

# .fly.secrets.yml
secretKey: <your secret value>

Files

By specifying a files property in your .fly.yml, it's possible to use fetch to load files without having to bundle them in your javascript directly.

Locally, these are fetched from your filesystem. Deployed, these are fetched from our distributed store.

Example usage in your code: (given a client/app.js file)

// index.js

addEventListener('fetch', function(event){
  event.respondWith(async function(){
    const res = await fetch("file://client/app.js")
    res.status // 200
    res.headers.set("content-type", "application/javascript")
    return res
  })
})

Note that fetching with the file: protocol returns a very basic response.

Multiple environments

Different environments (development, test, production) require different configurations. You can specify how each should behave by adding one level to your .fly.yml like:

config: &config # your default config
  foo: bar

default: &default
  app: your-app-name
  config:
    <<: *config

development:
  <<: *default

test:
  <<: *default
  config:
    <<: *config
    foo: not-bar

production:
  <<: *default
  config:
    <<: *config
    foo:
      fromSecret: fooSecret

Testing

fly comes with mocha as its default testing framework.

You can write unit tests and use fly test to run them within the fly environment:

// ./test/index.spec.js
import { MyModule } from '../my_module' // load some code
import { expect } from 'chai'

describe("MyModule", ()=>{
  it("works", function(){
    expect(MyModule).to.be.instanceof(Function)
  })
})

Deployment

Once you're happy with your app, you can deploy to fly.io.

1. Login

Use fly login to log into your fly.io account, if you don't have one, go create one!

2. Create an app

Make sure you've created your fly app for your account with fly apps:create [name] (name is optional)

Set your app property in your .fly.yml

3. Deploy!

Using fly deploy, here's what happens:

• Your code is bundled via webpack, it's also uglified to save space
• Your code, source map and files are added to a simple tarball, gzipped and uploaded to the fly.io API using your token
• We create a "release" for your app, those are immutable, changing anything (by using fly deploy or fly secrets:set) will trigger a new release which will be deployed automatically
• Your code is distributed instantly(-ish) across our global fleet of servers

Logs

Tail production logs with:

fly logs

Documentation

• Getting Started
• API Reference
• Examples

Open source

We develop fly in the open. We're Apache licensed and designed to run easily in local dev. You can deploy our core software to production, but it takes a little elbow grease and a fair amount of infrastructure. If you want to give this a try, let us know and we can help (and we would love related pull requests!).

Our commercial offering is built on top of this library, with additional code for managing certificates, distributed caching, and multi-tenant isolation. Over time we expect to extract many of these features, document them, and include them in our open source releases.

We support Let's Encrypt: We donate half our certificate management fees to Let's Encrypt every year.