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 app.json manifest. app.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 app.json files to your applications' source code. You and other developers can then easily deploy the source code into fully configured apps on Heroku, ready for further development.
The new app-setups endpoint in the Heroku Platform API leverages app.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
app.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 app.json:
{
"name": "Ruby on Rails",
"description": "A template for getting started with the popular Ruby framework.",
"website": "http://rubyonrails.org",
"success_url": "/welcome",
"addons": ["heroku-postgresql:hobby-dev", "papertrail"],
"env": {
"RAILS_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 app.json construct across our toolset and platform capabilities. Application galleries, Deploy on Heroku buttons for code repositories, app reconfiguration during git push and snapshotting a running app's configuration and environment are all exciting opportunities enabled by app.json. We are also eager to see all the different ways you'd use app.json and what additions you will make to these manifest files.
Getting the application running on Heroku
To set up an application on Heroku, 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.
Here’s output from a Go program that invokes this new endpoint:
$ # ./setup -apikey <api key> -archive https://github.com/heroku-examples/ruby-rails-sample/tarball/blog-example/
--> Created app fierce-reef-7523
----> App ID:42006200-c4ce-415e-8b76-8ce5ed7d960d
----> 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://fierce-reef-7523.herokuapp.com/welcome
<!DOCTYPE html>
<html>
<head>
<title>Ruby Rails Sample</title>
...
How it works
Heroku fetches the source code, parses the app.json manifest file found within the source bundle, creates the Heroku app and returns a response with an id that represents the setup. Then, Heroku orchestrates provisioning add-ons, building the source code, setting configuration variables, releasing the app, and running post-deployment scripts in an one-off dyno.
You can query the overall status of the setup using the id at anytime. You can also query the status of the build using the app name and build id. See the Introducing programmatic builds on Heroku 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 Heroku app with config vars and add-ons configured.
$ heroku config -a fierce-reef-7523
=== pacific-peak-6986 Config Vars
COOKIE_SECRET: 1e1867380b9365f2c212e31e9c43a87c17e82be0ce1a61406ea8274fac0680dc
DATABASE_URL: postgres://bdlgvbfnitiwtf:DGuFLR87rMNFe7cr_y1HGwadMm@ec2-54-225-182-133.compute-1.amazonaws.com:5432/d8p7bm6d7onr10
HEROKU_POSTGRESQL_ONYX_URL: postgres://bdlgvbfnitiwtf:DGuFLR87rMNFe7cr_y1HGwadMm@ec2-54-225-182-133.compute-1.amazonaws.com:5432/d8p7bm6d7onr10
PAPERTRAIL_API_TOKEN: VikcKA2wQf2H1ajww3s
RAILS_ENV: Production
SETUP_BY:
$ heroku addons -a fierce-reef-7523
=== pacific-peak-6986 Configured Add-ons
heroku-postgresql:hobby-dev HEROKU_POSTGRESQL_ONYX
papertrail:choklad
In addition to the running app, the source code is also available in a new Heroku git repo. To start making changes to your newly setup app, clone the Heroku git repo. You can then git push your changes directly to the Heroku git repo and see them reflected in the app.
$ heroku git:clone fierce-reef-7523
Cloning from app 'fierce-reef-7523'...
Cloning into 'fierce-reef-7523'...
Initializing repository, done.
remote: Counting objects: 77, done.
remote: Compressing objects: 100% (69/69), done.
remote: Total 77 (delta 2), reused 0 (delta 0)
Receiving objects: 100% (77/77), 17.85 KiB | 0 bytes/s, done.
Resolving deltas: 100% (2/2), done.
Checking connectivity... done
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 app.json files. Users can then run simple scripts or commands, in a few minutes see the samples running and continue working on them on Heroku. Take a look at one of these samples, starter-ruby.
Please see the app.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 Heroku interprets different sections of the app.json specification.
Together, app.json and the app-setups resource give you the building blocks to make first-time deployment a reliable, automated process for getting your code running and ready for further development. We are excitedly working on leveraging them in our tools and building new platform features around them. We are releasing the schema specification and API now so that we can get your feedback and hear from you on all the different ways you would leverage them. Reach us at api-feedback@heroku.com.