Skip to main content
Oct 19-21 HashiConf Global is live. Join Now
Type '/' to Search

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

$ 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

$ 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.

NOTE: Waypoint works best with Nomad 0.12.7 or later.

You can run Nomad locally in only a few seconds. A local instance of Nomad will work for this tutorial.

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

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

In this command, en0 is the primary network interface on your local system.

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'

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

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

»Setting up Nomad with Persistent Volumes

Waypoint installation on Nomad supports persistent data storage with host or csi volumes. See Nomad Stateful Workloads for set up instructions.

»Install the Waypoint server

NOTE: Due to a limitation in Docker, installing Waypoint on Nomad might result in an error message indicating you have an invalid IPv6 address format. This is because Docker for Mac and Windows does not yet support IPv6 IP Addresses. More information on this can be found here: docker daemon ipv6 support

NOTE: We strongly recommend using Consul for networking support in Nomad when running Waypoint servers. However, for this quickstart guide, you will set -nomad-consul-service=false to keep this introduction focused on Waypoint. Run the following command to install the Waypoint server job to Nomad. Note that there are a handful of options to use when installing Waypoint to Nomad. To see a full list of options, check out waypoint install -help. For now, run the following command to install Waypoint server.

To install Waypoint with host volume persistent storage, run:

$ waypoint install -platform=nomad -accept-tos -nomad-host-volume=<your_volume_name> -nomad-consul-service=false

$ waypoint install -platform=nomad -accept-tos -nomad-host-volume=<your_volume_name> -nomad-consul-service=false

To install Waypoint with csi volume persistent storage, run:

$ waypoint install -platform=nomad -accept-tos -nomad-csi-volume-provider=<csi_driver_provider> -nomad-csi-volume-capaity-min=<bytes> -nomad-csi-volume-capacity-max=<bytes> -nomad-csi-fs=<file-stytem> -nomad-consul-service=false

$ waypoint install -platform=nomad -accept-tos -nomad-csi-volume-provider=<csi_driver_provider> -nomad-csi-volume-capaity-min=<bytes> -nomad-csi-volume-capacity-max=<bytes> -nomad-csi-fs=<file-stytem> -nomad-consul-service=false

This tutorial shows installing a Waypoint server on Nomad with a host volume named "potato". Set up instructions here.

$ waypoint install -platform=nomad -accept-tos -nomad-host-volume=potato -nomad-consul-service=false

✓ Waypoint server ready
⚠️ Waypoint server running on Nomad is being accessed via its allocation IP and port.
This could change in the future if Nomad creates a new allocation for the Waypoint server,
which would break all existing Waypoint contexts.

We recommend using [Consul](https://www.consul.io/) for determining Waypoint server's IP running on Nomad rather than
relying on the static IP that is initially set up for this allocation.
✓ Server installed and configured!
✓ Installing runner...
✓ Waypoint runner installed
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-1633374897".
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".

To launch and authenticate into the Web UI, run:
waypoint ui -authenticate

Advertise Address: 192.168.0.178:22388
Web UI Address: https://192.168.0.178:9702

$ waypoint install -platform=nomad -accept-tos -nomad-host-volume=potato -nomad-consul-service=false
✓ Waypoint server ready⚠️ Waypoint server running on Nomad is being accessed via its allocation IP and port.This could change in the future if Nomad creates a new allocation for the Waypoint server,which would break all existing Waypoint contexts.
We recommend using [Consul](https://www.consul.io/) for determining Waypoint server's IP running on Nomad rather thanrelying on the static IP that is initially set up for this allocation.✓ Server installed and configured!✓ Installing runner...✓ Waypoint runner installedWaypoint server successfully installed and configured!
The CLI has been configured to connect to the server automatically. Thisconnection information is saved in the CLI context named "install-1633374897".Use the "waypoint context" CLI to manage CLI contexts.
The server has been configured to advertise the following address forentrypoint communications. This must be a reachable address for all yourdeployments. If this is incorrect, manually set it using the CLI command"waypoint server config-set".
To launch and authenticate into the Web UI, run:waypoint ui -authenticate
Advertise Address: 192.168.0.178:22388Web UI Address: https://192.168.0.178: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
mysql-server     service  50        running  2021-10-01T17:24:01-04:00
waypoint-runner  service  50        running  2021-10-04T15:15:26-04:00
waypoint-server  service  50        running  2021-10-04T15:14:57-04:00

$ nomad status
ID               Type     Priority  Status   Submit Datemysql-server     service  50        running  2021-10-01T17:24:01-04:00waypoint-runner  service  50        running  2021-10-04T15:15:26-04:00waypoint-server  service  50        running  2021-10-04T15:14:57-04:00

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

Nomad server

»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

$ 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"
      }
    }

  }

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.

NOTE: You might also want to update your docker image,location, and remove the local configuration if you plan to run this application on an external Nomad cluster. The current example uses a local based image.

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.

$ 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 orcommands 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 up
» Building...Creating new buildpack-based image using builder: heroku/buildpacks:18✓ Creating pack client⠴ Building image✓ Injecting entrypoint binary to imageGenerated new Docker image: example-nodejs:latestTagging Docker image: example-nodejs:latest» Deploying...» Configuring» Releasing...» Configuring
The deploy was successful! A Waypoint deployment URL is shown below. Thiscan be used internally to check your deployment and is not meant for externaltraffic. You can manage this hostname using "waypoint hostname."
           URL: https://instantly-worthy-shrew.waypoint.runDeployment URL: https://instantly-worthy-shrew--v1.waypoint.run

NOTE: It make take a few minutes to copy the image to the remote server, depending on the speed of your internet connection.

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.

The preview URL is optional and can be disabled in the Waypoint server configuration.

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

The deploy was successful! A Waypoint deployment URL is shown below. Thiscan be used internally to check your deployment and is not meant for externaltraffic. You can manage this hostname using "waypoint hostname."
           URL: https://instantly-worthy-shrew.alpha.waypoint.runDeployment URL: https://instantly-worthy-shrew--v1.alpha.waypoint.run

Waypoint creates the preview URL on a HashiCorp service. Because this preview URL is connected to your application and where it has been deployed, the URL will only show your application when it is running. In this walkthrough, this means that Docker Desktop and the container for the deployed example NodeJS application must both be running for the URL to render your application.

Web application

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

Nomad server

»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>

<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 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!

stdin: is not a tty