Deploy an Application to Nomad

Let's use Waypoint to deploy an application onto Nomad. This tutorial will give you a very quick overview of how Waypoint works.

»Prerequisites

In order to complete this tutorial, you will need access to a running Nomad cluster, such as one running in a public cloud or locally.

You'll need to install the waypoint binary locally, and clone the examples repository (detailed in the next section).

»Clone the examples repository

This walkthrough uses an example NodeJS application to show you how to build, deploy and release an application using Waypoint.

This example app is part of the Waypoint Examples repository. You will need a local clone of this repository on your computer to complete this walkthrough.

Clone the Waypoint Examples repository and navigate to the Nomad NodeJS example directory.

$ git clone https://github.com/hashicorp/waypoint-examples.git

Change into the subdirectory for the Nomad project. This project uses NodeJS, but the following instructions will work with any language that can be built with a cloud native buildpack.

$ cd waypoint-examples/nomad/nodejs

»Create a Nomad environment

Waypoint supports Nomad both as a location for running the Waypoint server and as a target to deploy and run application workloads on.

To get started with Nomad, review the HashiCorp Learn Nomad tutorials.

$ nomad agent -dev -network-interface="en0"

You will also want to export the NOMAD_ADDR environment variable. Waypoint will call this variable for interacting with the Nomad environment. In the case of a local environment, you should issue the following command.

$ export NOMAD_ADDR='http://localhost:4646'

Throughout this tutorial, you can view the Nomad UI at localhost:4646.

»Install the Waypoint server

Run the following command to install the Waypoint server job to Nomad.

$ waypoint install -platform=nomad -nomad-dc=dc1 -accept-tos

✓ Nomad allocation created
✓ Nomad allocation running
Waypoint server successfully installed and configured!

The CLI has been configured to connect to the server automatically. This
connection information is saved in the CLI context named "install-1602265890".
Use the "waypoint context" CLI to manage CLI contexts.

The server has been configured to advertise the following address for
entrypoint communications. This must be a reachable address for all your
deployments. If this is incorrect, manually set it using the CLI command
"waypoint server config-set".

Advertise Address: 127.0.0.1:29006
HTTP UI Address: 127.0.0.1:9702

You can verify the successful installation of the Waypoint server by running nomad status. You will observe the waypoint-server.

$ nomad status

ID               Type     Priority  Status   Submit Date
waypoint-server  service  50        running  2020-10-10T15:43:19-07:00

Or, visit the Nomad UI. You will observe the waypoint-server job.

»Initialize Waypoint

Before you can build and deploy your application, you must initialize it with Waypoint using the init command.

When you initialize Waypoint for your application, Waypoint determines if there is a Waypoint configuration file (waypoint.hcl) for the app in the directory.

The waypoint.hcl configuration file gives Waypoint instructions for how to build, deploy, and release your application.

If Waypoint cannot find the app's configuration file when you run waypoint init, Waypoint will create a starter waypoint.hcl file that you can then customize for your application.

»Examine the Waypoint.hcl File

The remainder of this walkthrough uses the example NodeJS application to show how to initialize an app and then build, deploy, and release it with Waypoint.

We will now view the waypoint.hcl file to learn more about the app's configuration.

In the waypoint-examples/nomad/nodejs/ directory, run the following command:

$ cat waypoint.hcl

The Terminal will output the contents of the waypoint.hcl file.

project = "example-nodejs"

  app "example-nodejs" {

    build {
      use "pack" {}
      registry {
          use "docker" {
            image = "nodejs-example"
            tag = "1"
            local = true
          }
      }
  }

    deploy {
      use "nomad" {
        datacenter = "dc1"
      }
    }

  }

The build clause defines how Waypoint will build the app. The pack option tells Waypoint to use the most relevant Cloud Native Buildpack to build the application. Since this example app is written for NodeJS, Waypoint will use NodeJS Buildpacks.

The deploy clause defines where Waypoint will deploy the app. The nomad and datacenter fields tell Waypoint to deploy the application to Nomad to the dc1 datacenter.

With these configurations in place, issue the following command in order to initialize Waypoint with this configuration.

$ waypoint init

✓ Configuration file appears valid
✓ Connection to Waypoint server was successful
✓ Project "example-nodejs" and all apps are registered with the server.
✓ Plugins loaded and configured successfully
✓ Authentication requirements appear satisfied.

Project initialized!

You may now call 'waypoint up' to deploy your project or
commands such as 'waypoint build' to perform steps individually.

»Deploy the application with waypoint up

This application is configured to use Cloud Native Buildpacks to detect the type of application running and to launch it within Nomad. Because Waypoint uses the applicable buildpack to create the Dockerfile, you do not need to create the file yourself.

Once Waypoint completes the build, it stores the artifacts in either a local or remote registry.

The registry clause in the waypoint.hcl file specifies where to store the app's artifacts. If the registry clause is not present, Waypoint will default to using the local docker instance to store the app's artifacts.

For this example application, Waypoint will store the image in a remote Docker repository after the app is built.

We can now deploy the application to Nomad by running waypoint up.

$ waypoint up

» Building...
Creating new buildpack-based image using builder: heroku/buildpacks:18
✓ Creating pack client
⠴ Building image
✓ Injecting entrypoint binary to image
Generated new Docker image: example-nodejs:latest
Tagging Docker image: example-nodejs:latest
» Deploying...
» Configuring
» Releasing...
» Configuring

The deploy was successful! A Waypoint deployment URL is shown below. This
can be used internally to check your deployment and is not meant for external
traffic. You can manage this hostname using "waypoint hostname."

           URL: https://instantly-worthy-shrew.waypoint.run
Deployment URL: https://instantly-worthy-shrew--v1.waypoint.run

Waypoint will show the progressive status of the build, deploy, and release steps in the terminal output. As part of the deployment workflow, Waypoint creates a preview URL for your application.

Waypoint will show the result of your deployment in the Terminal, along with your specific preview URL.

The deploy was successful! A Waypoint deployment URL is shown below. This
can be used internally to check your deployment and is not meant for external
traffic. You can manage this hostname using "waypoint hostname."

           URL: https://instantly-worthy-shrew.alpha.waypoint.run
Deployment URL: https://instantly-worthy-shrew--v1.alpha.waypoint.run

You can also view the server side of the deployment in the Nomad UI.

»Update and redeploy the application

One of the most powerful parts of Waypoint is its ability to iterate on deployments and quickly redeploy the application with your changes in place.

Open the following file in your preferred development editor:

view/pages/index.ejs

On about line 17, change the text to anything that you like, such as today's date.

<h1>This Node.js app was deployed with Waypoint on 1/1/2045.</h1>

Back in the Terminal, redeploy the application with your new and improved text.

$ waypoint up

Waypoint has now redeployed your application.

You will notice that the Deployment URL for this second deployment is different from what was created for the first deployment. Waypoint generates unique URLs for each deployment, which means that you can access each deployment by using their unique deployment URLs. This is typically used to preview a deployment before releasing it.

Now, open the new Deployment URL and verify that you see your modified text in the app. Congrats!