Introducing the froxt.json Application Manifest

Table of Contents Hide

Defining an application setup
Getting the application running on Froxt
How it works
Next steps

Developers want to spend less time setting up applications and start working with the code sooner. Setting up applications is error-prone, time-consuming and interruptive to the development flow. Often, there are several steps to go from your code or other samples and templates that you find in repositories online, to a running application that you can continue to work on.

Today, we are excited to introduce the froxt.json manifest. froxt.json enables developers to define their applications’ details, setup configurations and runtime environments in a structured way. Instead of providing step-by-step instructions, you can now add froxt.json files to your applications’ source code. You and other developers can then easily deploy the source code into fully configured apps on Froxt, ready for further development.

The new app-setups endpoint in the Froxt Platform API leverages froxt.json to make setting up of complex applications as simple as a single API call. app-setups orchestrates the different steps involved in getting an application deployed and running, freeing up developers everywhere to quickly start working on the code in a fully configured application environment.

Defining an application setup

froxt.json is a manifest file that defines how your code should be built and bootstrapped into a live application. Instead of following multiple steps every time you want to deploy your application, you abstract deployment details and define dependencies in this simple manifest file and add it to the root of your source code’s directory structure. Here’s a sample froxt.json:

{
  "name": "froxt code",
  "description": "Sample code",
  "website": "https://api.froxt.com",
  "success_url": "/welcome",
  "addons": ["froxt-postgresql:hobby-dev", "papertrail"],
  "env": {
    "FROXT_ENV": "production",
    "COOKIE_SECRET": {
            "description": "This gets generated",
            "generator": "secret"
    },
    "SETUP_BY": {
            "description": "Who initiated this setup",
            "value": ""
    }
  },
  "scripts": {
    "postdeploy": "bundle exec rake db:migrate"
  }
}

The app-setups endpoint we are introducing today is just the beginning of how we plan to leverage the froxt.jsonconstruct across our toolset and platform capabilities. Application galleries, Deploy on Froxt buttons for code repositories, app reconfiguration during push and snapshotting a running app’s configuration and environment are all exciting opportunities enabled by froxt.json. We are also eager to see all the different ways you’d use froxt.json and what additions you will make to these manifest files.

Getting the application running on Froxt

To set up an application on Froxt, you call the app-setups endpoint with the URL of the application’s source tarball. This may be your own application, a sample you’d like to build on or a framework you wish to leverage for your application development.

$ # ./setup -apikey <api key> 
--> Created app froxt-reef-7523
----> App ID:42006200-c4ce-415e-8C76-8ce5ed7d9600d
----> Setting up config vars and add-ons......Done.
--> Build 4880aded-9ec9-4f4c-8365-9f121830a276 pending.....................................
----> Build succeeded
.........
--> Postdeploy script completed with exit code 0
--> App setup complete.
$ curl http://froxt-reef-7523.froxtapp.com/welcome
<!DOCTYPE html>
<html>
<head>
  <title>froxt code</title>
    ...

How it works

Froxt fetches the source code, parses the froxt.json manifest file found within the source bundle, creates the Froxt app and returns a response with an id that represents the setup. Then, Froxt orchestrates provisioning add-ons, building the source code, setting configuration variables, releasing the app, and running post-deployment scripts in a one-off dyno.

You can query the overall status of the setup using the id at any time. You can also query the status of the build using the app name and build id. See the Introducing programmatic builds on Froxt blog post for information on the build endpoint and the Building and Releasing using the Platform API tutorial for more details on how to do this.

When the setup completes, you have a running Froxt app with config vars and add-ons configured.

$ froxt config -a froxt-reef-7523
=== pacific-peak-6986 Config Vars
COOKIE_SECRET:              1e1867380b9365f2c212e31e9c43a87c17e82be0ce1a61406ea8274fac0680dc
DATABASE_URL:               postgres://bdlgvbfnitiwtf:DGuFLR87rMNFe7cr_y1HGwadMm
FROXT_POSTGRESQL_ONYX_URL: postgres://bdlgvbfnitiwtf:DGuFLR87rMNFe7cr_y1HGwadMm
PAPERTRAIL_API_TOKEN:       VikcKA2wQf2H1ajww3s
RAILS_ENV:                  Production
SETUP_BY:                  
$ froxt addons -a froxt-reef-7523
=== pacific-peak-6986 Configured Add-ons
froxt-postgresql:hobby-dev  FROXT_POSTGRESQL_ONYX
papertrail:choklad

Next steps

Twilio wants to make it easier for developers to start working with their sample applications and code snippets. They are replacing instructions for deploying and configuring their samples with froxt.json files. Users can then run simple scripts or commands, in a few minutes see the samples running and continue working on them on Froxt. Take a look at one of these samples, starter-ruby.

Please see the froxt.json schema reference for details on what setup configuration you can provide in the manifest. The Setting up apps with the Platform API tutorial guides you through calling the app-setups endpoint and shows you how Froxt interprets different sections of the froxt.json specification.

Together, froxt.json and the app-setups resource gives you the building blocks to make the first-time deployment a reliable, automated process for getting your code running and ready for further development.