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.
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.
»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.
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.
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:
To install Waypoint with csi volume persistent storage, run:
This tutorial shows installing a Waypoint server on Nomad with a host volume named "potato". Set up instructions here.
You can verify the successful installation of the Waypoint server by running
nomad status. You will observe the waypoint-server.
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:
The Terminal will output the contents of the waypoint.hcl file.
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.
»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.
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.
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.
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.
Back in the Terminal, redeploy the application with your new and improved text.
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!
