Creating Your First Handel App

This page contains a tutorial for writing a simple Node.js “Hello World!” app and deploying it to AWS with the Handel tool.

Important

Before going through this tutorial, make sure you have installed Handel on your machine as shown in the Installation section.

Tutorial

This tutorial contains the following steps:

  1. Write the app
  2. Create your Handel file
  3. Deploy using Handel

Follow along with each of these steps in the sections below in order to complete the tutorial.

Write the app

We first need to create an app that you can run. We’re going to use Node.js to create an Express web service that will run in ElasticBeanstalk.

First create a directory for your application code:

mkdir my-first-handel-app
cd my-first-handel-app

Since it’s a Node.js application, the first thing you’ll need is a package.json file that specifies information about your app, including its dependncies. Create a file named package.json with the following contents:

{
    "name": "my-first-handel-app",
    "version": "0.0.1",
    "author": "David Woodruff",
    "dependencies": {
        "express": "^4.15.2"
    }
}

Now that you’ve got your package.json, install your dependencies from NPM:

npm install

Next, create a file called app.js with the following contents:

var app = require('express')();

app.get('/', function(req, res) {
    res.send("Hello World!");
});

var port = process.env.PORT || 3000;
app.listen(port, function () {
    console.log('Server running at http://127.0.0.1:' + port + '/');
});

Note

The above app code uses Express to set up a web server that has a single route “/”. That route just responds with the string “Hello World!”.

Test your app by starting it up:

node app.js

Once it’s started up, you should be able to go to http://localhost:3000/ to see it working. You should see a page that says “Hello World!” on it.

Create your Handel file

Now that you’ve got a working app, you need to create a Handel file specifying how you want your app deployed. Create a file called handel.yml with the following contents:

version: 1

name: my-first-handel-app # This is a string you choose for the name of your app.

environments:
  dev: # This is the name of your single environment you specify.
    webapp: # This is the name of your single service inside your 'dev' environment.
      type: beanstalk # Every Handel service requires a 'type' parameter
      path_to_code: . # This contains the path to the directory where your code lives that should be sent to Beanstalk
      solution_stack: 64bit Amazon Linux 2017.03 v4.3.0 running Node.js # This specifies which Beanstalk 'solution stack' should be used for the app.

Note

See the Handel File section for full details on how the Handel file is structured.

Note

We only specified the required parameters for Beanstalk. There are others that have defaults if you don’t specify them. See the Beanstalk service documentation for full information on all the different parameters for the service.

Deploy using Handel

Important

In order to run Handel to deploy your app, you must be logged into your AWS account on the command line. You can do this by setting your AWS access keys using the AWS CLI.

See Configuring the AWS CLI for help on doing this once you’ve installed the AWS CLI.

Now that you’ve written your app, created your Handel file, and obtained your account config file, you can run Handel to deploy:

handel deploy -c default-us-east-1 -e dev -v 1

Note

In the above command, the following arguments are provided:

  • The -c parameter specifies which Account Config File to use. Specifying default-us-east-1 here tells Handel you don’t have one and just want to use the default VPC AWS provides in the us-east-1 region.
  • The -e parameter is a comma-separated string list that specifies which environments from your Handel file you want to deploy
  • The -v parameter is an arbitrary string specifying the current version being deployed.

Once you’ve executed that command, Handel should start up and deploy your application. You can sign into the AWS Console and go to the “ElasticBeanstalk” service to see your deployed application.

Next Steps

Now that you’ve deployed a simple app using Handel, where do you go next?

Learn more about Handel

Read through the following documents in the Handel Basics section:

Those documents will give you more information on the design and usage of Handel, particularly how you can use Handel’s dependencies to wire services together.

Learn how to configure the different service types

Once you understand Handel’s basic configuration, see the Supported Services section, which contains information about the different services you can deploy using Handel. Each service page in that section will give the following information:

  • How to configure the service in your Handel file.
  • How to consume the service in other services (if applicable).
  • How to produce events to other services (if applicable).

Set up a continuous delivery pipeline

Handel can run anywhere, from your laptop to a build server. The recommended way to run Handel is inside a Continuous Delivery pipeline. There are many options available on the market, and AWS provides the CodePipeline service for creating these pipelines.

Handel provides a companion tool, called Handel-CodePipeline, that helps you easily create these CodePipelines running Handel for your deploy.