Deploy an Application to Nomad

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, with host volumes enabled. The Stateful Workloads with Nomad Host Volumes tutorial covers how to to create a host volume and configure a Nomad client to use it.

While it is possible to have the server and runner share the same Nomad volume, we recommend having two host volumes set up - one for the Waypoint server and one for the Waypoint runner.

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.

Setting up Nomad with Persistent Volumes

Waypoint installation on Nomad supports persistent data storage with host or CSI volumes but this tutorial will focus on host volumes.

See Nomad Stateful Workloads for set up instructions that cover both host and CSI volumes.

Example host volume setup

Setting up a host volume on a Nomad client is done by adding the host_volume stanza to the client stanza in a client configuration file.

This snippet from a client configuration file will create two host volumes.

# ...
client {
  enabled = true
  host_volume {
    wp-server-vol {
      path = "/nomad/host-volumes/wp-server"
      read_only = false
    }
    wp-runner-vol {
      path = "/nomad/host-volumes/wp-runner"
      read_only = false
    }
  }
  # ...
}
# ...

Then the client configuration file can be provided to the agent command with the -config flag.

$ nomad agent -config=nomad-client.hcl

The volumes can then be seen in the Nomad UI when inspecting the client.

Install the Waypoint server

Run the following command to install the Waypoint server job to Nomad. To see a full list of options for the install command, add the -help flag or check the waypoint install command documentation page.

$ waypoint install -platform=nomad -accept-tos \
  -nomad-host-volume=wp-server-vol \
  -nomad-runner-host-volume=wp-runner-vol \
  -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.

It is recommended to use Consul for determining Waypoint servers IP running on Nomad rather than
relying on the static IP that is initially set up for this allocation.
✓ Configured server connection
✓ Successfully connected to Waypoint server in Nomad!
✓ Server installed and configured!
✓ Runner "static" installed
✓ Registered ondemand runner!
✓ Initializing Nomad client...
✓ Waypoint runner installed
✓ Runner "static" adopted successfully.
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-1667590727".
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.1.6:9701
Web UI Address: https://192.168.1.6: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-server         service  50        running  2021-10-04T15:14:57-04:00
waypoint-static-runner  service  50        running  2021-10-04T15:15:26-04: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!