HashiCorp Developer AI Private beta now available Sign up today
Waypoint
Waypoint Home

Deploy an Application to Nomad

Warning

This content is part of the legacy version of Waypoint that is no longer actively maintained. For additional information on the new vision of Waypoint, check out this blog post and the HCP Waypoint documentation.

In this tutorial, you will learn how Waypoint works by deploying and running an application on a Nomad cluster that's running on your local machine.

If you want to try Waypoint on a Nomad cluster running on cloud infrastructure, complete the get started with Nomad on the cloud tutorials.

Prerequisites

For this tutorial, you will need:

Create a Nomad environment

Waypoint supports Nomad both as a location for running the Waypoint server and as a target for application deployments.

Waypoint installation on Nomad supports persistent data storage with host or CSI volumes. In this tutorial, you use host volumes for persistent storage, and will set up one for both the server and client runner. While it is possible to have the server and runner share the same Nomad volume, we recommend having separate host volumes.

Create the Nomad client configuration

Host volumes are configured in the Nomad client HCL file with the host_volume block. Waypoint uses these host volumes to write the data it needs for the server and client runner.

Note

The $HOME environment variable used in this tutorial is automatically set to the user's home directory on most systems. If it is not already set on your system, export the path to your home directory as $HOME.

export $HOME=/path/to/home/directory

Create a folder named nomad in your home directory. This will contain the host volume directories, the data directory for the server, and the client configuration file.

$ mkdir $HOME/nomad

Create the data directory for the server.

$ mkdir $HOME/nomad/datadir

Then, create the host volume directories for the server and runner. The -p flag will create the parent host-volumes directory.

$ mkdir -p $HOME/nomad/host-volumes/wp-server && mkdir $HOME/nomad/host-volumes/wp-runner

Change to your home directory.

$ cd $HOME

Create a file named nomad-client.hcl and add the following configuration to it. Replace the PATH_TO_HOME_DIR placeholder text with the full path to your home directory. Save the file. Note that the data directory and host volume paths must be absolute.

nomad-client.hcl
bind_addr = "0.0.0.0"
data_dir = "PATH_TO_HOME_DIR/nomad/datadir"
server {
  enabled = true
  bootstrap_expect = 1
}

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

Create the Nomad cluster. Note that the client configuration file is passed in with the -config flag. Nomad will start and begin to output data.

Leave this terminal session open to keep Nomad running.

$ nomad agent -config=nomad-client.hcl
==> WARNING: Bootstrap mode enabled! Potentially unsafe operation.
==> Loaded configuration from nomad-client.hcl
==> Starting Nomad agent...
==> Nomad agent configuration:

       Advertise Addrs: HTTP: 192.168.50.210:4646; RPC: 192.168.50.210:4647; Serf: 192.168.50.210:4648
            Bind Addrs: HTTP: [0.0.0.0:4646]; RPC: 0.0.0.0:4647; Serf: 0.0.0.0:4648
                Client: true
             Log Level: INFO
                Region: global (DC: dc1)
                Server: true
               Version: 1.5.2

==> Nomad agent started! Log data will stream in below:

    2023-03-29T15:59:28.862-0400 [INFO]  nomad: setting up raft bolt store: no_freelist_sync=false
    2023-03-29T15:59:28.906-0400 [INFO]  nomad.raft: initial configuration: index=1 servers="[{Suffrage:Voter ID:6bb056e7-a71b-2328-9012-7d00668ea8c4 Address:192.168.50.210:4647}]"
    # ...
    2023-03-29T15:59:28.914-0400 [INFO]  client: using state directory: state_dir=/Users/edu/nomad/datadir/client
    2023-03-29T15:59:28.915-0400 [INFO]  client: using alloc directory: alloc_dir=/Users/edu/nomad/datadir/alloc
    #...
    2023-03-29T15:59:35.146-0400 [INFO]  client: started client: node_id=feb6cf8a-e396-e006-6bab-02827001cb8c
    2023-03-29T15:59:35.187-0400 [INFO]  client: node registration complete

In a new terminal session, export the cluster address to an environment variable.

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

The Nomad UI is available at http://localhost:4646/ui.

Inspect the host volumes

The host volumes for the Waypoint runner and server can be seen in the Nomad UI when inspecting the client. Open the Nomad UI, click on the Clients link from the left navigation, click on the client from the client list, and scroll down to the Host Volumes section.

Note that there are two host volumes in the list, one for the Waypoint runner with the name wp-runner-vol and one for the Waypoint server with the name wp-server-vol.

Nomad UI showing the host volumes of a client

Set up Waypoint

HCP Waypoint is a HashiCorp-managed service that helps you to manage your application lifecycle without maintaining a Waypoint server and associated infrastructure. It allows to you automate and simplify the process of deploying your web applications into your infrastructure.

Waypoint runs as a server and a client, whether run on HCP Waypoint or locally. For this tutorial, you can choose to use HCP Waypoint for the server and your Nomad cluster for the client or run Waypoint entirely on the cluster.

Both methods create a Waypoint context that contains information about the server and authentication for connecting to it from the Waypoint CLI. This is how the CLI knows the address of the server when you run other Waypoint commands.

Set up an HCP organization and project

Sign in to your HCP account and create an HCP organization by following the steps in the Create an organization page. Then, create an HCP project by following the steps in the Create a project page.

Enable HCP Waypoint

Click on the Waypoint option from the left navigation.

HCP UI with the Waypoint option highlighted

Then, click on the Activate Waypoint button in the top right of the page.

HCP Waypoint UI with the Activate Waypoint button highlighted

A dialog appears to confirm that Waypoint has been activated.

HCP Waypoint UI a dialog showing that Waypoint has been activated

Set up HCP Waypoint context

Click the Manage button on the top right of the page, click on the clipboard icon to copy the waypoint context create command, and run it in your terminal. Your Waypoint CLI can now communicate with HCP Waypoint.

HCP Waypoint UI with the Manage button clicked and copy button highlighted

HCP Waypoint works with your local installation of the Waypoint CLI and does not require any additional runners as it uses the one that is part of the CLI. Installing and connecting a static runner to HCP Waypoint allows you to automate your workflow with GitOps and use dynamic configuration sourcing without requiring interaction with your CLI.

This tutorial uses only the CLI runner and does not include runner installation. You can read more about the runner installation process on the runner install page.

Clone the example repository

The example repository contains application code and Waypoint configuration files for building, deploying, and releasing the application with Waypoint.

Clone the example repository.

$ git clone https://github.com/hashicorp-education/learn-waypoint-get-started.git

Navigate to the example-app directory.

$ cd nomad-local/example-app

Initialize Waypoint for the application

You must initialize and configure Waypoint for your application before beginning the build, deploy, and release workflow.

During the initialization process, Waypoint searches for a waypoint.hcl configuration file for the application in the current directory. This configuration file gives Waypoint instructions for how to build, deploy, and release your application. If Waypoint cannot find the configuration file when waypoint init is run, it will create a waypoint.hcl file that you can then customize for your application.

Review the waypoint.hcl file

Open the waypoint.hcl file.

nomad-local/example-app/waypoint.hcl
project = "nomad-nodejs"

app "nomad-nodejs-web" {

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

  deploy {
    use "nomad" {
      datacenter = "dc1"
      namespace  = "default"
      service_provider = "nomad"
    }
  }
}

The use option within the build, deploy, and release blocks specifies which plugin to use during those specific phases of the workflow.

The build block defines how Waypoint will build the application and produce an artifact.

The deploy block defines how Waypoint will deploy the application.

Waypoint URL service

The Waypoint URL service is a service hosted by HashiCorp that generates publically accessible URLs for your applications on Waypoint. The URLs are connected to your application and their deployment locations so the URLs will only resolve when the deployment is running.

These preview URLs are optional and can be disabled in the Waypoint server configuration when running a server manually with waypoint server run. You can also disable preview URLs on a per-app basis with the url block if the service is enabled on the server.

Disable the URL service for a specific app
project = "example-project"

app "example-application" {
  url {
    auto_hostname = false
  }
  
  # ...
}

Initialize Waypoint

Initialize Waypoint for the example application.

$ waypoint init
✓ Configuration file appears valid
✓ Connection to Waypoint server was successful
✓ Project "nomad-nodejs" and all apps are registered with the server.
✓ Project "nomad-nodejs" pipelines are registered with the server.

Project initialized!

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

Build and deploy

With the initialization complete, use the waypoint up command to instruct Waypoint to build, deploy, and release your application.

Run waypoint up

Waypoint uses Cloud Native Buildpacks to automatically detect the type of application and uses the applicable buildpack to create the build artifact.

Once Waypoint completes the build, it stores the artifacts in a registry. The registry block contains the configuration for where Waypoint should store those artifacts. By default, Waypoint stores Docker artifacts locally with Docker Desktop unless the registry block contains additional configuration.

Start the Waypoint workflow.

$ waypoint up

Waypoint will start the process and output the following.

» Building nomad-nodejs-web...
â ™ Running build v1

» Performing operation locally
Creating new buildpack-based image using builder: heroku/buildpacks:20
✓ Creating pack client
✓ Building image
 │ [exporter] Adding layer 'buildpacksio/lifecycle:process-types'
 │ [exporter] Adding label 'io.buildpacks.lifecycle.metadata'
 │ [exporter] Adding label 'io.buildpacks.build.metadata'
 │ [exporter] Adding label 'io.buildpacks.project.metadata'
 │ [exporter] Setting default process type 'web'
 │ [exporter] Saving nomad-nodejs-web...
 │ [exporter] *** Images (482b7fc8b561):
 │ [exporter]       nomad-nodejs-web
 │ [exporter] Adding cache layer 'heroku/nodejs-engine:dist'
 │ [exporter] Reusing cache layer 'heroku/nodejs-npm:toolbox'
✓ Injecting entrypoint binary to image

Generated new Docker image: nomad-nodejs-web:latest
✓ Running push build v1
✓ Tagging Docker image: nomad-nodejs-web:latest => nomad-nodejs-web:1
✓ Docker image pushed: nomad-nodejs-web:1

» Deploying nomad-nodejs-web...
✓ Running deploy v1
✓ Job registration successful
✓ Allocation "02157784-81fe-b488-d36d-5f8a7ea22e8c" created: node "feb6cf8a-e396-e006-6bab-02827001cb8c", group
"nomad-nodejs-web-01gwsybfftps09nm9gd20vtzj7"
✓ Evaluation status changed: "pending" -> "complete"
✓ Evaluation "83f2b372-3bf2-994f-a205-3d198de0debd" finished with status "complete"
✓ Deployment successfully rolled out!
✓ Finished building report for Nomad platform
✓ Job "nomad-nodejs-web-01gwsybfftps09nm9gd20vtzj7" is reporting ready!

✓ Finished building report for Nomad platform
✓ Job "nomad-nodejs-web-01gwsybfftps09nm9gd20vtzj7" is reporting ready!

» Releasing nomad-nodejs-web...
✓ Running release v1
No release phase specified, skipping...

» Variables used:
  VARIABLE | VALUE | TYPE | SOURCE  
-----------+-------+------+---------


The deploy was successful!

The release did not provide a URL and the URL service is disabled on the
server, so no further URL information can be automatically provided. If
this is unexpected, please ensure the Waypoint server has both the URL service
enabled and advertise addresses set.

Waypoint shows the progress of the build, deploy, and release steps in the output but does not contain deployment URLs as the URL service is disabled when using HCP Waypoint.

View the application's URL by first finding the allocation ID of the job with the nomad job status command. The allocation ID is at the bottom of the output under Allocations. In this example the allocation ID is b0a9be89.

$ nomad job status nomad-nodejs
[...]
Allocations
ID        Node ID   Task Group                                   Version  Desired  Status   Created   Modified
b0a9be89  882f3098  nomad-nodejs-web-01gz47w8vq758dgn9grwk2d40s  0        run      running  3m7s ago  2m56s ago

Copy the allocation ID and get the status for the allocation. This command will filter the status output and display the allocation addresses. In this example, the address is 192.168.50.210:30298. Open this address in your browser to see the application.

$ nomad alloc status b0a9be89 | grep -A 3 "Allocation Addresses"
Allocation Addresses (mode = "host"):
Label      Dynamic  Address
*waypoint  yes      192.168.50.210:30298 -> 3000

The example application showing deployment text

Update and redeploy the app

One of the most powerful parts of Waypoint is that it allows you to quickly iterate on and redeploy changes to your application.

Open index.ejs in your text editor and update the deployment message in the <h1> tag. Save the file.

nomad-local/example-app/views/pages/index.ejs
<section class="content">
  <div class="language-icon">
    <img src="/language.svg" alt="Node.js Icon" />
  </div>
  <h1>This Node.js app was updated and redeployed with Waypoint!</h1>
  <p>
    Try making a change to this text locally and run <code>waypoint up</code> again to see it.
  </p>
  <p>
    Read the <a href="https://waypointproject.io/docs">documentation</a> for more about Waypoint.
  </p>
</section>

Navigate back to your terminal and restart the workflow.

$ waypoint up

Waypoint will start the process and output the following.

» Building nomad-nodejs-web...
â ™ Running build v2

» Performing operation locally
Creating new buildpack-based image using builder: heroku/buildpacks:20
✓ Creating pack client
✓ Building image

# ...

Generated new Docker image: nomad-nodejs-web:latest
✓ Running push build v2
✓ Tagging Docker image: nomad-nodejs-web:latest => nomad-nodejs-web:1
✓ Docker image pushed: nomad-nodejs-web:1

» Deploying nomad-nodejs-web...
✓ Running deploy v2
✓ Job registration successful
✓ Allocation "04518bc2-c940-c101-30e3-10e03149cf45" created: node "feb6cf8a-e396-e006-6bab-02827001cb8c", group
"nomad-nodejs-web-01gwt040bta2j0364q8xhzrgxs"
✓ Evaluation status changed: "pending" -> "complete"
✓ Evaluation "cf7d7314-ee6b-6598-7879-31d5f61dc31d" finished with status "complete"
✓ Deployment successfully rolled out!
✓ Finished building report for Nomad platform
✓ Job "nomad-nodejs-web-01gwt040bta2j0364q8xhzrgxs" is reporting ready!

» Releasing nomad-nodejs-web...
✓ Running release v2
No release phase specified, skipping...

# ...

The deploy was successful!

# ...

Find the allocation ID of the job with the nomad job status command. In this example the allocation ID is b0a9be89.

View the jobs that start with nomad-nodejs. Each deployment with Waypoint creates a new Nomad job so there are now two available jobs.

$ nomad job status nomad-nodejs
ID                                           Type     Priority  Status   Submit Date
nomad-nodejs-web-01gz49t5b2cnsf401fj6pw56q3  service  10        running  2023-04-28T12:05:50-04:00
nomad-nodejs-web-01gz49x96wh23hdgawna1377j5  service  10        running  2023-04-28T12:07:32-04:00

The results are in order from oldest to newest. Copy the second job ID and get the job status for it. In this example, the job ID is nomad-nodejs-web-01gz49x96wh23hdgawna1377j5.

$ nomad job status nomad-nodejs-web-01gz49x96wh23hdgawna1377j5
[...]
Allocations
ID        Node ID   Task Group                                   Version  Desired  Status   Created     Modified
eb4524bc  feb6cf8a  nomad-nodejs-web-01gz49x96wh23hdgawna1377j5  0        run      running  6m59s ago  6m48s ago

Copy the allocation ID and get the status for the allocation. In this example, the address is not 192.168.50.210:29908. Open this address in your browser.

$ nomad alloc status eb4524bc | grep -A 3 "Allocation Addresses"
Allocation Addresses (mode = "host"):
Label      Dynamic  Address
*waypoint  yes      192.168.50.210:29908 -> 3000

The updated example application with new text

Next steps

In this tutorial, you learned about Waypoint and the application workflow, set up a Waypoint server and client on Nomad, and built, deployed, updated, and redeployed an application.

Learn how to deploy applications to other platforms with Waypoint by checking out the Docker and Kubernetes tutorials.

Continue on to the next tutorial by clicking on the Next button below. You will learn how to interact with a running application container and browse the Waypoint web UI.

Be sure to follow the steps in the Destroy the Deployment tutorial to uninstall the Waypoint components and clean up your Nomad cluster.

Edit this page on GitHub