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
  4. Delete the created app

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 2018.03 v4.5.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.

If you work for an organization that uses federated logins through something like ADFS, then you’ll have a different process for logging in on the command-line. In this case, ask your organization how they login to AWS on the command-line.

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

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

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.

Delete the created app

Since this was a tutorial using a Hello World app, we want to delete it now that we’re done with it. To delete your app, run the following command:

handel delete -c default-us-east-1 -e dev

When you execute the above command, it will show you something like this confirmation prompt:

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
WARNING: YOU ARE ABOUT TO DELETE YOUR HANDEL ENVIRONMENT 'dev'!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

If you choose to delete this environment, you will lose all data stored in the environment!

In particular, you will lose all data in the following:

* Databases
* Caches
* S3 Buckets
* EFS Mounts

PLEASE REVIEW this environment thoroughly, as you are responsible for all data loss associated with an accidental deletion.
PLEASE BACKUP your data sources before deleting this environment just to be safe.

? Enter 'yes' to delete your environment. Handel will refuse to delete the environment with any other answer:

Type yes and hit Enter, and Handel will proceed to delete the environment.

Congratulations, you’ve finished the tutorial!

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.