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 will also need to have a local copy of the Waypoint Examples repository.
»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.
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"
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'
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.
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.
»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
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
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.
<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!