isabella232 / guide-node

Guides for using Habitat with Node. Find out more at http://habitat.sh

Before and After: Packaging a Node Application with Habitat

Table of contents

• Introduction
• The Before and After, Explained
  • Tools for the job
  • Adding Habitat
    • Initialize Habitat
    • Configure the application
    • Test your Plan
• FAQ
• What's Next?

Introduction

Each directory in this repo contains a functioning "Hello World" application whose purpose is to provide a simple example of what an application looks like after Habitat has been added. By switching between the start and finish branches, you'll quickly get an idea of what exactly is involved.

• 01-basic This basic Hello World application demonstrates adding Habitat from scratch.
• 02-basic-scaffolding Here you will see how scaffolding simplifies the setup process by introspecting the application and generating the Habitat plan files for you.
• 03-basic-framework In addition to using scaffolding, this example adds the Express framework to the mix. (spoiler alert: the scaffolding works the same; no additional setup is required).

Not familiar with Habitat and why you would add it to your application? Check out the FAQ section.

The Before and After, Explained

Tools for the job

For the purposes of this before-and-after demonstration, you do not need to install anything. That said, the following tools would need to be present on your workstation in order to write plans and build packages.

1. Habitat CLI tool
2. Docker

For the curious, you can find installation instructions in the docs.

Adding Habitat

As you switch between the start and finish branches of this repo, you'll notice several files are added. An explanation of how and why those files are added can be found below.

Initializing Habitat

• Generate a Habitat Plan

  • Explore the /habitat directory for each application while on the finish branch.
  • The Habitat Plan is the key component when adding Habitat to an application. In these examples, it is simplest to think of the Plan as being equivalent to the /habitat directory. A Plan consists of several files, the most prominent being plan.sh, along with several configuration and hook files described below. Learn more about writing plans in the docs.
  • Plan files can be written from scratch or you can generate a starter set using the hab plan init command. The latter method was used to create the initial 01-basic /habitat directory.
  • Alternatively, you can use scaffolding to generate a more complete set of Plan files. This is the case for the 02-basic-scaffolding & 03-basic-framework example applications. By simply adding a flag - hab plan init -s node - Habitat can introspect the application and handle much of the configuration for you. Note that you won't see a /hooks directory for these two sample applications as they're auto-generated by scaffolding during build time. You can still add hook files if you need them, effectively overriding the scaffolding. Learn more about scaffolding in the docs.

• Side note about package.json

  • Standard for many Node applications, it defines your application requirements. The example applications are simple enough that they don't necessitate a package.json. However, the Node scaffolding relies upon the existence of this file. For that reason, you'll see it present in the 02-basic-scaffolding & 03-basic-framework directories.

Configuring the application

• Template the configuration settings

  • View the config/config.json & default.toml files for each application while on the finish branch.
  • Optionally included, the default.toml file contains a set of TOML variables that can be used to generate dynamic configuration files.
  • By templating your configuration settings, you’ll not only be able to re-use these defined values when you build and run your packages, but you'll also be empowered to leverage the Habitat Supervisor for things such as runtime configuration (e.g. apply a new config.json). Learn more about the Habitat Supervisor features in the docs.

• Tell the Habitat Supervisor how to start and run the application

  • View the hooks/init & hooks/run files for the 01-basic application while on the finish branch.
  • The plan.sh file provides information for packaging the application, whereas hook files contain additional instructions for running the application.
  • Since scaffolding generates the hooks at build time, you will not see any init or run files in the 02-basic-scaffolding & 03-basic-framework examples. However, you can override those generated settings by simply adding hook files to the /hooks directory. Learn more about hooks in the docs.

Testing your Plan

As you're writing your Plan files, you'll want to periodically check whether your application package will successfully build and run. This section goes beyond the sample apps to describe how the local development workflow might look when you're Habitizing your app.

• Building packages in the Habitat Studio
  • The Habitat Studio is a clean, self-contained, minimal environment in which you can develop, build, and package software that is free from any upstream operating system distribution. Learn more about the Habitat Studio in the docs.
  • Once you've entered the Studio (hab studio enter from the application repo's root), you simply run the build command. This will generate a Habitat artifact (.hart) file that gets stored in a /results directory.
• Running the Habitized application
  • At this point, you could start your new package directly within the Habitat Studio, or you could optionally export it to another format and run it outside the Studio. Learn more about running packages in the docs.
• Exporting the build artifact
  • .hart files can be optionally exported into multiple external, immutable runtime formats. For example, you could export the 02-basic-scaffolding .hart to a Docker image by simply running hab pkg export docker yourorigin/02-basic-scaffolding. Learn more about exporting packages in the docs.
• About docker-compose.yml
  • While Habitat applications can be run with no additional tooling, as described above, we’ve added a sample docker-compose.yml to this repo in order to demonstrate a familiar and simple way to run the Habitized applications locally. After exporting the .hart into a Docker image, you would simply exit the Studio and run docker-compose up or a typical Docker run command like docker run -it -p 8080:8080 yourorigin/02-basic-scaffolding and preview it in your browser.

FAQ

What is Habitat and what can it do for me?

Habitat consists of three core components:

1. a packaging system
2. a build system and
3. a process supervisor.

With a single download, you’ll be able to automate your workflow and ship your applications with everything they need to run and be managed. Whether it's to bring consistency to how you build and deploy your applications, to gain more control over your application in production, or to move your applications to a cloud-native state, Habitat has you covered.

Habitat is language and platform agnostic which means you can use it to build, deploy, and manage all of your applications, both new and old, in a consistent manner.

Can I use parts of Habitat?

Yes, you can choose to use only what you need and add more capabilities as you get more comfortable. For example, you might have Jenkins build your Habitat artifact (.hart) and deploy it using your existing CI/CD workflow, then use the Habitat supervisor to manage your application. Alternatively, you could replace your current workflow and use the Habitat Build Service to create and promote new builds that are automatically picked up by the Supervisor.

You can also defer making platform decisions until a later date. Start packaging your applications today and choose a platform service later (e.g. export to Docker images), it’s up to you.

How do I add Habitat to an application?

That’s precisely what the sample apps in this repo will demonstrate! Essentially, you’ll add a Habitat Plan which consists of a few files - a plan.sh along with a some configuration and hook files. There are a couple of ways to do this (with and without scaffolding) that you’ll see in these examples.

What's next?

Now that you’re a bit more familiar with the basics, you can turn your attention to some more in-depth materials:

• Join us on Slack and get answers to your questions
• View the Habitat project on GitHub
• Try the hands-on Build Service demo
• Complete the Habitat Tutorials
• Browse the Docs for further technical details
• Return to the habitat.sh website