Run a NodeJS application onto AWS Elastic Container Service (ECS) with Waypoint

Deploy an Application to AWS Elastic Container Service

Deploy a Ruby application onto AWS Lambda with Waypoint

Deploy an Application onto AWS Lambda

Azure

Deploy an application onto an Azure Container Instance with Waypoint

Deploy an application onto an Azure Container Instance

Use static and dynamic values in Waypoint applications.

Configuration

Use and change environment variables in your application.

Static Application Configuration

Use and change custom input variables in your application.

Input Variables

Start using Waypoint in only a few minutes on a local Docker instance.

Get Started - Docker

Waypoint enables you to publish any application to any platform with a single file and a single command. Build, deploy, and release applications programmatically using HashiCorp Configuration Language.

Introduction to Waypoint

Install the Waypoint binary locally on Mac, Linux, or Windows, manually or using a package manager (Homebrew).

Install Waypoint

Deploy a Waypoint application locally to Docker.

Use Waypoint with Docker

Exec into a container, view logs, and use the web UI.

Debugging and UI

Destroy the Deployment

Build, deploy, and release applications to a Kubernetes cluster.

Get Started - Kubernetes

Release applications to a local or cloud hosted Kubernetes cluster.

Deploy an Application to Kubernetes

Remove your application from the cluster.

Destroy the Deployment from Kubernetes

Build, deploy, and release applications to a Nomad cluster.

Get Started - Nomad

Release applications to a local or cloud hosted Nomad cluster.

Deploy an Application to Nomad

Google Cloud

Run an application on Google Cloud Run with Waypoint

Deploy an Application to Google Cloud Run

Learn to define your build, deploy, and release lifecycle with Waypoint.

Docs

Commands

Plugins

Community


With Waypoint, it is quick and easy to deploy and release applications on [AWS Lambda](https://aws.amazon.com/lambda).

In this tutorial, you will use Waypoint's [AWS Lambda
plugin](https://www.waypointproject.io/plugins/aws-lambda) to build a Docker image containing a Ruby application, push it to a [Elastic Container Registry (ECR)](https://aws.amazon.com/ecr/) repository, then deploy the image to Lambda. Afterwards, you will update the application and deploy the updated application.

## Prerequisites

You'll need to install [`waypoint` 0.3.0 or greater locally](/tutorials/waypoint/get-started-install), clone the example repository (detailed in the next section), set up your AWS credentials, and create an Elastic Container Registry.

You'll be most comfortable if you have already used Waypoint to do a local deployment with our [Get Started](/collections/waypoint/get-started-docker) collection.

**Optional**: Provision a Kubernetes cluster and install the Waypoint server to Kubernetes in order to unlock all Waypoint functionality (including application `logs`, `exec`, and `ui` access).

### Clone the examples repository

The code for this tutorial is in the `hashicorp/waypoint-examples` repository. Clone the repository with git.

```shell-session
$ git clone https://github.com/hashicorp/waypoint-examples.git
```

Change into the cloned repository. This project uses Ruby but the following instructions will work with any language that can be built with a cloud native buildpack.

```shell-session
$ cd aws/lambda/ruby
```

## Install the Waypoint server

The Waypoint server must be installed. You may install it locally which requires fewer steps but limits the functionality of some Waypoint commands. Or, install to a Kubernetes or Nomad cluster for full functionality (including the `logs`, `exec`, and `ui` commands).

<Tabs>
<Tab heading="Local">


You can run the Waypoint server locally in Docker in order to achieve a minimal deployment of your applications on ECS.

~> **Note:** A local server used with a remote deployment only supports limited functionality. The `logs`, `exec`, and other commands require a remote server with a remote deployment.

Install the Waypoint server to your local Docker instance.

```shell-session
$ waypoint install --platform=docker -accept-tos
```

If you run into any errors, see the [troubleshooting](https://www.waypointproject.io/docs/troubleshooting#waypoint-server-in-docker) page which has instructions for resetting the Waypoint server in Docker.

</Tab>
<Tab heading="Remote">


For full functionality, provision an [EKS](https://aws.amazon.com/eks/) cluster and install the Waypoint server.

Follow the [EKS Terraform tutorial](/tutorials/terraform/eks?in=terraform/kubernetes) which includes a Terraform configuration for provisioning the cluster. You must also configure your local `kubectl` command to communicate to the remote cluster (instructions are included in the tutorial).

Then, run the [install command](/tutorials/waypoint/get-started-kubernetes?in=waypoint/get-started-kubernetes#install-the-waypoint-server) to deploy the Waypoint server to the cluster.

```shell-session
$ waypoint install --platform=kubernetes -accept-tos

service/waypoint created
statefulset.apps/waypoint-server created
```

Verify the installation by running `kubectl get all`. If the installation was successful you will observe that the single container in the `waypoint-server-0` pod is ready and the pod has a status of `Running`.

```shell-session
$ kubectl get all

NAME                    READY   STATUS    RESTARTS   AGE
pod/waypoint-server-0   1/1     Running   0          2m34s

NAME                 TYPE           CLUSTER-IP      EXTERNAL-IP                                                               PORT(S)                         AGE
service/kubernetes   ClusterIP      172.20.0.1      <none>                                                                    443/TCP                         71m
service/waypoint     LoadBalancer   172.20.39.252   aaa.us-west-2.elb.amazonaws.com   9701:32038/TCP,9702:32208/TCP   2m35s

NAME                               READY   AGE
statefulset.apps/waypoint-server   1/1     2m35s
```

</Tab>
</Tabs>


## Explore `waypoint.hcl`

Open the
[`waypoint.hcl`](https://github.com/hashicorp/waypoint-examples/tree/main/aws/lambda/ruby/waypoint.hcl)
file. In this section, you will explore the `build`, `deploy`, and `release` steps for this
project.

- The `waypoint.hcl` file uses the `aws-ecr` registry plugin during the `build` stage. The `aws-ecr` plugin uses your AWS credentials and internally builds the correct URL to the AWS API.

  It is also possible to configure this manually with the `docker` plugin. Other configuration options are listed in the [plugin documentation](https://www.waypointproject.io/plugins/aws-ecs#aws-ecr-registry).

  ```hcl
  build {
    use "pack" {}
    registry {
      use "aws-ecr" {
        region     = "us-west-2"
        repository = "learn-waypoint-lambda"
        tag = "howdy-waypoint-lambda"
      }
    }
  }
  ```

- Use the `aws-lambda` plugin for the `deploy` stage. The `region` paramter is required, but you can specify the `iam_role`, `memory` and `timeout` for your Lambda function. See the [plugin documentation](https://www.waypointproject.io/plugins/aws-lambda#aws-lambda-platform) for other configuration options.

  ```hcl
  deploy {
    use "aws-lambda" {
      region = "us-west-2"
    }
  }
  ```

- Finally, Waypoint will release your application using the `aws-alb` plugin, which will provision an Application Load Balancer (ALB) to serve traffic to your Lambda endpoint.

  ```hcl
  release {
    use "aws-alb" {
    }
  }
  ```

## Initialize Waypoint

Initialize the project with the `init` command.

```shell-session
$ waypoint init

✓ Configuration file appears valid
✓ Connection to Waypoint server was successful
✓ Project "learn-waypoint-lambda" and all apps are registered with the server.
✓ Plugins loaded and configured successfully

Project initialized!

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

Read the [troubleshooting](https://www.waypointproject.io/docs/troubleshooting#waypoint-server-in-docker) page if you run into any errors.

## Build, deploy, and release the application

Deploy the application with `up`. Waypoint will error the first time when attempting to provision Lambda. This is expected behavior and will be resolved in a future release.

-> **Tip:** This may take a few minutes to execute, especially if this is the first time that you push the image to the registry.

```shell-session
$ waypoint up

» Building...
✓ Initializing Docker client...
✓ Building image...
 │ Step 1/3 : FROM public.ecr.aws/lambda/ruby:2.7
 │  ---> bf1ae62b40c7
 │ Step 2/3 : COPY handler.rb /var/task
 │  ---> Using cache
 │  ---> 449fcc61fefb
 │ Step 3/3 : CMD [ "handler.handler" ]
 │  ---> Using cache
 │  ---> c9f49c4cda3d
 │ Successfully built c9f49c4cda3d
 │ Successfully tagged waypoint.local/learn-waypoint-lambda:latest
✓ Injecting Waypoint Entrypoint...
✓ All services available.
✓ Set ECR Repository name to 'learn-waypoint-lambda'
✓ Tagging Docker image: waypoint.local/learn-waypoint-lambda:latest =>
REDACTED.dkr.ecr.us-west-2.amazonaws.com/learn-waypoint-lambda:howdy-waypoint-lamb
✓ Pushing image...
 │ 05446996bee6: Layer already exists
 │ 6e41f142768a: Layer already exists
 │ 3907e39be0d6: Layer already exists
 │ 3557feb0c34d: Layer already exists
 │ d6fa53d6caa6: Layer already exists
 │ a4da7ecab4a8: Layer already exists
 │ 1a75a887b22d: Layer already exists
 │ 647149dcba32: Layer already exists
 │ howdy-waypoint-lambda: digest: sha256:1c0b5e3f6aa11c1e9e3615c315940ed39323678ffe
 │ c55e4bf4676f06e93339c0 size: 2000
Docker image pushed:
REDACTED.dkr.ecr.us-west-2.amazonaws.com/learn-waypoint-lambda:howdy-waypoint-lamb

» Deploying...
✓ Connecting to AWS
❌ Creating new Lambda function
! InvalidParameterValueException: The role defined for the function cannot be
  assumed by Lambda.
  {
    RespMetadata: {
      StatusCode: 400,
      RequestID: "87c1babd-51d3-41b6-8d3d-2fe3b0100714"
    },
    Message_: "The role defined for the function cannot be assumed by Lambda.",
    Type: "User"
  }
```

Rerun `waypoint up` to deploy Lambda and the ALB.

```
$ waypoint up

## ...

» Deploying...
✓ Connecting to AWS
✓ Creating new Lambda function
✓ Published Lambda function: arn:aws:lambda:us-west-2:REDACTED:function:learn-waypoint-lambda:8 (8)
✓ Creating TargetGroup for Lambda version

» Releasing...

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

   Release URL: http://waypoint-learn-waypoint-lambda-380235335.us-west-2.elb.amazonaws.com
Deployment URL: https://evenly-ethical-kid--v2.waypoint.run
```

Visit the Release URL or the Deployment URL to view the application running on Lambda.

![Web application](/img/waypoint/aws/lambda-web-app.png)

Try appending `?name=Turing` to the Release or Deployment URL (for example: `http://waypoint-learn-waypoint-lambda-1827600373.us-west-2.elb.amazonaws.com/?name=Turing`). The service will return a welcome message with the name you inserted.

![Web application](/img/waypoint/aws/lambda-web-app-turing.png)

You can visit the [Lambda console](https://us-west-2.console.aws.amazon.com/lambda/home?region=us-west-2#/functions?f0=true&n0=false&op=and&v0=learn-waypoint-lambda) to verify the deployed Lambda function.

![Lambda Console showing deployed Lambda function](/img/waypoint/aws/lambda-console.png)

## Update Lambda function

You can schedule a new application deployment through Waypoint.

First, update the welcome message in `handler.rb`.

```diff hideClipboard
require 'json'

def handler(event:, context:)
    # ..
    {
         # ..
-        "body": "<html><body><h1>Howdy #{name} from Lambda!</h1></html></body>"
+        "body": "<html><body><h1>Hello #{name} from Lambda!</h1></html></body>"
    }
end
```

Then, redeploy your application with the `up` command.

```shell-session
$ waypoint up

✓ Initializing Docker client...
✓ Building image...
 │ Step 1/3 : FROM public.ecr.aws/lambda/ruby:2.7
 │  ---> bf1ae62b40c7
 │ Step 2/3 : COPY handler.rb /var/task
 │  ---> Using cache
 │  ---> 449fcc61fefb
 │ Step 3/3 : CMD [ "handler.handler" ]
 │  ---> Using cache
 │  ---> c9f49c4cda3d
 │ Successfully built c9f49c4cda3d
 │ Successfully tagged waypoint.local/learn-waypoint-lambda:latest
✓ Injecting Waypoint Entrypoint...
✓ All services available.
✓ Set ECR Repository name to 'learn-waypoint-lambda'
✓ Tagging Docker image: waypoint.local/learn-waypoint-lambda:latest => REDACTED.dkr.ecr.us-west-2.amazonaws.com/learn-waypoint-lambda:howdy-waypoint-lambda
✓ Pushing image...
 │ 05446996bee6: Layer already exists
 │ 6e41f142768a: Pushed
 │ 3907e39be0d6: Layer already exists
 │ 3557feb0c34d: Layer already exists
 │ d6fa53d6caa6: Layer already exists
 │ a4da7ecab4a8: Layer already exists
 │ 1a75a887b22d: Layer already exists
 │ 647149dcba32: Layer already exists
 │ howdy-waypoint-lambda: digest: sha256:0868aec4c9d5c3512227c165653b2f260b2ed0e264
 │ 7eebe28972e0675a94dc7b size: 2000
Docker image pushed: REDACTED.dkr.ecr.us-west-2.amazonaws.com/learn-waypoint-lambda:howdy-waypoint-lambda

» Deploying...
✓ Connecting to AWS
✓ Updating Lambda function with new code
✓ Published Lambda function: arn:aws:lambda:us-west-2:REDACTED:function:learn-waypoint-lambda:9 (9)
✓ Creating TargetGroup for Lambda version

» Releasing...

» Pruning old deployments...
  Deployment: 01F2QSDA65SVZBA9RSM3NVQKKT

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

   Release URL: http://waypoint-learn-waypoint-lambda-380235335.us-west-2.elb.amazonaws.com
Deployment URL: https://evenly-ethical-kid--v3.waypoint.run
```

Visit the Release URL or the Deployment URL to view the application running on Lambda.

-> **Tip:** It might take a couple of minutes for the Lambda function to warm up.

![Web application](/img/waypoint/aws/updated-lambda-web-app.png)

Notice that Lambda is returning the updated welcome message.

## Destroy the instance

To deprovision the container, run `destroy`.

```shell-session
$ waypoint destroy

» Destroying shared deploy resources for application 'learn-waypoint-lambda'...
✓ Connecting to AWS
✓ Deleting Lambda function
✓ IAM role deleted
Destroy successful!
```

If there is an error, try again after a few seconds.

~> **Note:** The `destroy` command will not delete container images in the registry or the ECS cluster itself. Visit the [ECR console](https://us-west-2.console.aws.amazon.com/ecr/repositories?region=us-west-2) to manually delete the entire registry or individual container images.

## Next steps

In this tutorial, you deployed a web application with Waypoint.

AWS Lambda can also be used to deploy an API Gateway or schedule periodic tasks as with `cron`.

Experiment with omitting the `aws-alb` releaser if you want to use Waypoint to build and deploy a container but use other AWS features with your deployed container.

Learn more about Waypoint by following along with the other [tutorials](/waypoint) for Azure, Google Cloud, and others, or read the documentation for other Waypoint [plugins](https://www.waypointproject.io/plugins).



This walkthrough runs on your computer with Docker Desktop and will give you a very quick overview of how Waypoint works.

By the end of this tutorial, you'll be running an application in Docker with Waypoint. Applications are available in Java, Next.js, NodeJS, Ruby, and other languages.

Follow this tutorial to run an application locally in Docker with Waypoint, and to learn how Waypoint works. Applications are available in Java, Next.js, NodeJS, Ruby, and other languages. To deploy apps to Kubernetes with Waypoint, try the [Kubernetes collection](/collections/waypoint/get-started-kubernetes).

> **NOTE:** An interactive tutorial is available for this tutorial. Click the **Show Terminal** button to start.

<LabToggleButton />

## Prerequisites

You must install the [`waypoint` binary installed locally](https://learn.hashicorp.com/tutorials/waypoint/get-started-install) in order to complete the remaining steps in this tutorial. You should also:

- Clone the code examples repository
- Install and run Docker Desktop

### Clone the examples repository

This tutorial uses an example Ruby application to show you how to build, deploy and release using Waypoint.

This example app is part of the [Waypoint Examples applications](https://github.com/hashicorp/waypoint-examples) repository. Clone this repository on your computer to complete this tutorial.

Clone the Waypoint Examples repository.

```shell-session
$ git clone https://github.com/hashicorp/waypoint-examples.git
```

Navigate to the `docker/ruby` directory. Notice that the Docker example directory contains example applications in other programming languages as well.

```shell-session
$ cd waypoint-examples/docker/ruby
```

### Install and run Docker Desktop

Install the most recent stable version of [Docker Desktop](https://www.docker.com/products/docker-desktop).

## Set up the Waypoint server

Waypoint runs as a server and a client, even if only run locally. For this tutorial, you'll run the server in Docker Desktop.

### Install the Waypoint Server

Install the Waypoint server to Docker Desktop on your computer. This allows you to view the user interface, collaborate on deployments, and more.

Run the following command to install the Waypoint server. The `-accept-tos` flag
confirms that you accept the terms of service for our [application URL
service](https://waypointproject.io/terms).

```shell-session
$ waypoint install -platform=docker -accept-tos
```

Waypoint's output will indicate that the server container has started and that your local CLI is configured to communicate with it.

```plaintext
✓ Server container started
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-1601411904".
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: waypoint-server:9701
HTTP UI Address: localhost:9702
```

You may also install the server to a Kubernetes cluster or a [Nomad cluster](https://nomadproject.io). To learn more about Kubernetes, see the getting started guide for [deploying an application to Kubernetes](/tutorials/waypoint/get-started-kubernetes). The walkthrough shows you how to deploy the server and an example app to Kubernetes.

-> **NOTE:** The install command creates a context that points to the newly
created server with authentication. This is how your local Waypoint CLI knows the address of the server when you run
later Waypoint commands.

### About the Server Workflow

When you deploy your app with Waypoint, your computer (the Waypoint client) connects
to the Waypoint server to initiate the Waypoint workflow. The client then registers
itself as a runner, allowing Waypoint to run builds on it.

When the build is completed, the Waypoint server sends the build artifacts, such as a container image,
to the artifact registry of your choice. Multiple Waypoint clients can concurrently
connect to a single server to deploy and release applications.

## Initialize and Configure Waypoint for Your Application

Before you can build and deploy your application, you must initialize it with Waypoint. For a blank application, this is done with the `init` command.

When you initialize Waypoint for your application, Waypoint first looks to see if there is a Waypoint configuration file (`waypoint.hcl`) for the application in the current directory. If Waypoint cannot find the application's configuration file when you run `waypoint init`, Waypoint will create a starter `waypoint.hcl` file that you can then customize for your application.

The `waypoint.hcl` configuration file gives Waypoint instructions for how to build, deploy, and release your application.

### Examine the `waypoint.hcl` file

The `waypoint-examples` repository contains `waypoint.hcl` files for each of the example applications in the `docker` subdirectory. View the `waypoint.hcl` file to learn more about the application's configuration.

Open `waypoint.hcl` in your editor, or run the following command in the `waypoint-examples/docker/ruby/` directory.

```shell-session
$ cat waypoint.hcl
```

<Tabs>
<Tab heading="Ruby" group="Ruby">


```hcl
project = "example-ruby"

app "example-ruby" {
  labels = {
    "service" = "example-ruby",
    "env" = "dev"
  }

  build {
    use "pack" {}
  }

  deploy {
    use "docker" {}
  }
}
```

</Tab>
<Tab heading="Java" group="Java">


```hcl
project = "example-java"

app "example-java" {
  labels = {
    "service" = "example-java",
    "env" = "dev"
  }

  build {
    use "pack" {}
  }

  deploy {
    use "docker" {}
  }
}
```

</Tab>
<Tab heading="Next.js" group="Next.js">


```hcl
project = "example-nextjs"

app "example-nextjs" {
  labels = {
    "service" = "example-nextjs",
    "env" = "dev"
  }

  build {
    use "pack" {}
  }

  deploy {
    use "docker" {}
  }
}
```

</Tab>
<Tab heading="NodeJS" group="NodeJS">


```hcl
project = "example-nodejs"

app "example-nodejs" {
  labels = {
    "service" = "example-nodejs",
    "env" = "dev"
  }

  build {
    use "pack" {}
  }

  deploy {
    use "docker" {}
  }
}
```

</Tab>
</Tabs>


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. If the app is written in Ruby, Waypoint will use Ruby Cloud Native Buildpacks, or if the app is written in NodeJS, Waypoint will use NodeJS Cloud Native
Buildpacks, and so forth.

The `deploy` clause defines how Waypoint will deploy the app. The `docker` option tells Waypoint to deploy the application to Docker.

Alternate configuration for each of these steps is provided by Waypoint [plugins](https://www.waypointproject.io/plugins).

### Initialize Waypoint for the Example App

Run the `init` command to initialize the application.

```shell-session
$ waypoint init
```

Waypoint will initialize the application and output a message in the Terminal window.

```plaintext
✓ Configuration file appears valid
✓ Local mode initialized successfully
✓ Project "example-ruby" 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.
```

You can now move on to building and deploying the application.

## Build and Deploy

### Run `waypoint up`

This application is configured to use Cloud Native Buildpacks to detect the type of application running and to launch it within Docker. 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 application's artifacts.

For this example application, Waypoint will store the image on the local Docker instance after it is built.

Deploy the application to Docker Desktop by running `waypoint up`.

```shell-session
$ waypoint up
```

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. Either URL can be used to view the application.

```plaintext
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--01EJ0F2VYWTNTYJ6FNFNTY44G9.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 Ruby application must both be running for the URL to render your application.

![Waypoint Web Application](/img/waypoint/get-started/web-app.png)

## Update and Redeploy the App

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.

<Tabs>
<Tab heading="Ruby" group="Ruby">


Open the following file in your preferred development editor:

`app/views/welcome/index.erb`

</Tab>
<Tab heading="Java" group="Java">


Open the following file in your preferred development editor:

`src/main/resources/templates/index.html`

</Tab>
<Tab heading="Next.js" group="Next.js">


Open the following file in your preferred development editor:

`pages/index.js`

</Tab>
<Tab heading="NodeJS" group="NodeJS">


Open the following file in your preferred development editor:

`views/pages/index.ejs`

</Tab>
</Tabs>


Find the line that says "app was deployed with Waypoint" and add today's date or any text.

```html
...
<h1>This Ruby on Rails app was deployed with Waypoint on 1/1/2045.</h1>
...
```

Back in the Terminal, redeploy the application with your new and improved text.

```shell-session
$ waypoint up
```

Waypoint has now redeployed your application to Docker.

Notice that the Deployment URL for this second deployment is different from 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 your modified text is in the application. Congrats!

-> For Docker deployments, both deploys will be active for the non-Deployment specific URL. As such, accessing that URL will return requests from both deployments.



Waypoint uses both a client and a server to build, deploy, and release
applications. This functionality is all available from a single binary.

<Tabs>
<Tab heading="Manual installation">

Get Waypoint by downloading a pre-compiled `waypoint` binary or compiling it from source.

To install Waypoint, find the [appropriate package](https://www.waypointproject.io/downloads) for your system and download it as a zip archive.

After downloading Waypoint, unzip the package. Waypoint runs as a single
binary named `waypoint`. Any other files in the package can be safely removed
and Waypoint will still function.

Finally, make sure that the `waypoint` binary is available on your `PATH`. This process will differ depending on your operating system.

<Tabs>
<Tab heading="Mac or Linux">

Print a colon-separated list of locations in your `PATH`.

```shell-session
$ echo $PATH
```

Move the Waypoint binary to one of the listed locations. This command assumes that the binary is currently in your downloads folder and that your `PATH` includes `/usr/local/bin`, but you can customize it if your locations are different.

```shell-session
$ mv ~/Downloads/waypoint /usr/local/bin/
```

For more detail about adding binaries to your path, see [this Stack Overflow article](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux).

</Tab>
<Tab heading="Windows">

[This Stack Overflow article](https://stackoverflow.com/questions/1618280/where-can-i-set-path-to-make-exe-on-windows)
contains instructions for setting the PATH on Windows through the user interface.

</Tab>
</Tabs>
</Tab>
<Tab heading="Homebrew on OS X">

[Homebrew](https://brew.sh) is a free and open-source package management system
for Mac OS X. Install the official [Waypoint
formula](https://github.com/hashicorp/homebrew-tap) from the terminal.

Register the HashiCorp tap as a source.

```shell-session
$ brew tap hashicorp/tap
```

Then install Waypoint.

```shell-session
$ brew install hashicorp/tap/waypoint
```

~> **NOTE:** This installs a signed binary and is automatically updated with
every new official release.

To update to the latest, run

```shell-session
$ brew upgrade hashicorp/tap/waypoint
```

</Tab>
<Tab heading="Scoop on Windows">

[Scoop](https://scoop.sh/) is a free and open-source package management system
for Windows. Install Waypoint from the command-line.

```shell-session
$ scoop install waypoint
```

~> **NOTE:** The [Scoop main bucket
repository](https://github.com/ScoopInstaller/Main/blob/master/bucket/waypoint.json)
is **NOT** maintained by HashiCorp. The latest version of Waypoint is always
available by manual installation.

</Tab>
<Tab heading="Linux">

HashiCorp officially maintains and signs packages for the following Linux distributions.

<Tabs>
<Tab heading="Ubuntu/Debian">

Add the HashiCorp [GPG key][gpg-key].

```shell-session
$ curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo apt-key add -
```

Add the official HashiCorp Linux repository.

```shell-session
$ sudo apt-add-repository "deb [arch=amd64] https://apt.releases.hashicorp.com $(lsb_release -cs) main"
```

Update and install.

```shell-session
$ sudo apt-get update && sudo apt-get install waypoint
```

</Tab>
<Tab heading="CentOS/RHEL">

Install `yum-config-manager` to manage your repositories.

```shell-session
$ sudo yum install -y yum-utils
```

Use `yum-config-manager` to add the official HashiCorp Linux repository.

```shell-session
$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
```

Install.

```shell-session
$ sudo yum -y install waypoint
```

</Tab>
<Tab heading="Fedora">

Install `dnf config-manager` to manage your repositories.

```shell-session
$ sudo dnf install -y dnf-plugins-core
```

Use `dnf config-manager` to add the official HashiCorp Linux repository.

```shell-session
$ sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/fedora/hashicorp.repo
```

Install.

```shell-session
$ sudo dnf -y install waypoint
```

</Tab>
<Tab heading="Amazon Linux">

Install `yum-config-manager` to manage your repositories.

```shell-session
$ sudo yum install -y yum-utils
```

Use `yum-config-manager` to add the official HashiCorp Linux repository.

```shell-session
$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/AmazonLinux/hashicorp.repo
```

Install.

```shell-session
$ sudo yum -y install waypoint
```

</Tab>
</Tabs>

-> **TIP:** Now that you have added the HashiCorp repository, you can install
[Terraform](/tutorials/terraform/install-cli),
[Vault](/tutorials/vault/getting-started-install),
[Consul](/tutorials/consul/get-started-install),
[Nomad](/tutorials/nomad/get-started-install) and
[Packer](/tutorials/packer/get-started-install) with the same command.

</Tab>
</Tabs>

One of the functions of the install task is that it creates a
[context](https://waypointproject.io/commands/context-list) that points to the
newly created server with the appropriate authentication. This is how Waypoint
knows the address of the server when you run other Waypoint commands.

## Validate the installation

Validate the installation by running the `waypoint` command.

```
$ waypoint
Usage: waypoint [-version] [-help] [-autocomplete-(un)install] <command> [args]

Common commands:
    release      Release a deployment.
    up           Perform the build, deploy, and release steps for the app.
    build        Build a new versioned artifact from source.
...
```

[gpg-key]: https://apt.releases.hashicorp.com/gpg 'HashiCorp GPG key'



Deploying applications in the DevOps landscape can be confusing with so many
services, configuration files, and workflows to decode. But as a developer, you
just want to deploy.

Waypoint is a tool that enables you to publish any application to any platform
with a single file and a single command: `waypoint up`. Read this page to learn
about the high level operation of Waypoint. Then, follow the next tutorials to
install, set up, and run Waypoint.

We built Waypoint so you can focus on the thing you love: web application
development with JavaScript, Python, PHP, Java, Ruby, or any other language.

The standard Waypoint workflow involves two commands and one file: `waypoint
init`, `waypoint up` and `waypoint.hcl`. Waypoint will automatically generate a
`waypoint.hcl` file with reasonable defaults when you initialize it, if your
application doesn't have one.

Waypoint's minimal configuration file uses the same syntax you are familiar with
in Terraform, but asks you to write very little of it (as few as a dozen lines).

Once you've initialized Waypoint, you can deploy your applications with
`waypoint up`.

Waypoint can [build](https://www.waypointproject.io/docs/lifecycle/build) your
application into a disk image,
[deploy](https://www.waypointproject.io/docs/lifecycle/deploy) it to your
favorite cloud platform, and
[release](https://www.waypointproject.io/docs/lifecycle/release) it to the
public.

A typical build, deploy, and release workflow requires many configuration files.
You _can_ create these and use them with Waypoint, but you don't have to. A
single `waypoint.hcl` file dynamically packages your application, publishes it
to a public or private container registry, configures Kubernetes, Nomad, or
another application scheduler, and releases your application to a public URL
with HTTPS included.

![Files](/img/waypoint/get-started/intro-files.png)

We've designed Waypoint based on what we've learned from years of building
developer tools. Waypoint includes
[hooks](https://www.waypointproject.io/docs/lifecycle/hooks) so you can easily
extend its core functionality. A powerful [plugin
system](https://www.waypointproject.io/docs/plugins) connects you to cloud
platforms. We know you'll want to include Waypoint in your continuous deployment
workflow, so we've built examples for [GitHub
Actions](https://www.waypointproject.io/docs/automating-execution/github-actions),
[CircleCI](https://www.waypointproject.io/docs/automating-execution/circle-ci),
and [Jenkins](https://www.waypointproject.io/docs/automating-execution/jenkins).

Developers just want to deploy.

Install Waypoint to get started!



Let's use Waypoint to deploy applications onto Kubernetes. 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 Kubernetes
cluster, such as one running in a public cloud, in Docker Desktop, or in
[`kind`](https://kind.sigs.k8s.io/).

You'll need to install the [`waypoint` binary locally](/tutorials/waypoint/get-started-install),
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
applications](https://github.com/hashicorp/waypoint-examples). 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 Kubernetes NodeJS
example directory.

```shell-session
$ git clone https://github.com/hashicorp/waypoint-examples.git
```

Change into the subdirectory for the Kubernetes project. This project uses NodeJS
but the following instructions will work with any language that can be built with
a cloud native buildpack.

```shell-session
$ cd waypoint-examples/kubernetes/nodejs
```

### Create a Kubernetes environment

You can use any current Kubernetes distribution with Waypoint. Set your KubeConfig
with the `KUBECONFIG` environment variable to allow access to the cluster.

<Tabs>
<Tab heading="Docker Desktop" group="Docker">


[Docker Desktop](https://www.docker.com/products/docker-desktop) for running local
Docker resources. It has a built-in Kubernetes feature for running a local Kubernetes
cluster.

<Tabs>
<Tab heading="Mac">


To enable Kubernetes on your local machine, navigate to the Preferences screen
and select the check box labeled "Enable Kubernetes".

![MacOS](/img/waypoint/get-started/docker-desktop-preferences.png)

</Tab>
<Tab heading="Windows">


To enable Kubernetes on your local machine, navigate to the Settings screen and
select the check box labeled "Enable Kubernetes".

![Windows](/img/waypoint/get-started/docker-desktop-settings.png)

</Tab>
</Tabs>


Then click the "Apply & Restart" button. After a few moments, Docker Desktop
will restart with and active Kubernetes cluster. You can verify your local
configuration by running any command against `kubectl`.

```shell-session
$  kubectl get all

NAME                 TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
service/kubernetes   ClusterIP   10.96.0.1    <none>        443/TCP   24m
```

</Tab>
<Tab heading="kind" group="kind">



[Kind](https://kind.sigs.k8s.io/docs/user/quick-start/) is a tool for running a
local Kubernetes cluster.

Create a cluster with the `create` command.

```shell-session
$ kind create cluster
```

The `create` command will also configure `kubectl` to use the new cluster for
operations.

Verify the existence of the new cluster by running `get clusters`.

```shell-session
$ kind get clusters
```

</Tab>
<Tab heading="AWS EKS" group="EKS">


This tutorial can be run against the [AWS Elastic Kubernetes
Service](https://aws.amazon.com/eks/) and the [Elastic Container
Registry](https://console.aws.amazon.com/ecr/get-started?region=us-east-1).

The easiest way to get started is by provisioning an EKS cluster with our
[Terraform EKS
tutorial](/tutorials/terraform/eks?in=terraform/kubernetes).

Once you have completed the "Configure kubectl" section in the EKS tutorial, you
will be properly configured to run commands with `kubectl` against the cluster.
Return to this guide to continue using Waypoint.

~> **NOTE**: The Terraform tutorial uses `us-east-2` for the example, but this
tutorial uses `us-east-1`. The examples will still work, but be sure to modify
any commands to use the appropriate region.

Verify that you have a running Kubernetes cluster by checking the [EKS
console](https://us-east-1.console.aws.amazon.com/eks/home?region=us-east-1#/clusters)
before continuing.

![EKS Console](/img/waypoint/aws/aws-eks-cluster.png)

You can also verify your local configuration by running a command against `kubectl`.

```shell-session
$ kubectl get all

NAME                 TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
service/kubernetes   ClusterIP   172.20.0.1   <none>        443/TCP   57m
```

Next, create an
[ECR](https://console.aws.amazon.com/ecr/get-started?region=us-east-1) registry
named `waypoint-example` (or any other available name).

![ECR Form](/img/waypoint/aws/aws-ecr-form.png)

Verify that you have a running container registry by checking the [ECR
console](https://console.aws.amazon.com/ecr/repositories?region=us-east-1) and
can see the registry.

![ERC Successfully Created](/img/waypoint/aws/aws-ecr-created.png)

</Tab>
<Tab heading="GCP GKE" group="GKE">


This tutorial can be run against a [GCP
GKE](https://cloud.google.com/kubernetes-engine) cluster and the [Google
Container Registry](https://cloud.google.com/container-registry).

The easiest way to set up a cluster is to follow our [GKE
tutorial](/tutorials/terraform/gke?in=terraform/kubernetes).

Once you have completed the "Configure kubectl" section in the GKE tutorial, you
will be properly configured to run commands with `kubectl` against the cluster.
Return to this guide to continue using Waypoint.

Or, you can visit the [GKE
console](https://console.cloud.google.com/kubernetes/list) and create a cluster.
Any size will work, including the "My first cluster" quick start.

![GCP Kubernetes Console](/img/waypoint/get-started/gcp-create-cluster.png)

You can verify your local configuration by running any command against `kubectl`.

```shell-session
$ kubectl get all

NAME                 TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
service/kubernetes   ClusterIP   172.20.0.1   <none>        443/TCP   57m
```

The Google Container Registry will be available to your application without
requiring any additional steps.

</Tab>
</Tabs>


## Install the Waypoint server

Now that you have created a Kubernetes environment, install the Waypoint server
on it with the `install` command. The `-accept-tos` flag confirms that you
accept the terms of service for our [application URL
service](https://waypointproject.io/terms).

```shell-session
$ waypoint install --platform=kubernetes -accept-tos

service/waypoint created
statefulset.apps/waypoint-server created
```

You can verify that the cluster was successfully created by running `kubectl get all`.
You should see the `waypoint-server-0` pod. The exact output will vary based on
your Kubernetes platform.

<Tabs>
<Tab heading="Docker Desktop" group="Docker">


```shell-session
$ kubectl get all

NAME                    READY   STATUS    RESTARTS   AGE
pod/waypoint-server-0   1/1     Running   0          79s

NAME                 TYPE          CLUSTER-IP      EXTERNAL-IP   PORT(S)                         AGE
service/kubernetes   ClusterIP     10.96.0.1       <none>        443/TCP                         30m
service/waypoint     LoadBalancer  10.101.171.80   localhost     9701:31110/TCP,9702:32273/TCP   81s

NAME                               READY   AGE
statefulset.apps/waypoint-server   1/1     80s
```

</Tab>
<Tab heading="kind" group="kind">


```shell-session
$ kubectl get all

NAME                    READY   STATUS    RESTARTS   AGE
pod/waypoint-server-0   1/1     Running   0          2m34s
```

</Tab>
<Tab heading="AWS EKS" group="EKS">


```shell-session
$ kubectl get all

NAME                    READY   STATUS    RESTARTS   AGE
pod/waypoint-server-0   1/1     Running   0          2m34s

NAME                 TYPE           CLUSTER-IP      EXTERNAL-IP                                                               PORT(S)                         AGE
service/kubernetes   ClusterIP      172.20.0.1      <none>                                                                    443/TCP                         71m
service/waypoint     LoadBalancer   172.20.39.252   aaa.us-east-1.elb.amazonaws.com   9701:32038/TCP,9702:32208/TCP   2m35s

NAME                               READY   AGE
statefulset.apps/waypoint-server   1/1     2m35s
```

</Tab>
<Tab heading="GCP GKE" group="GKE">


```shell-session
$ kubectl get all

NAME                    READY   STATUS    RESTARTS   AGE
pod/waypoint-server-0   1/1     Running   0          2m34s
```

You can also visit the [GKE console](https://console.cloud.google.com/kubernetes/list)
and find the `waypoint-server` StatefulSet.

![Waypoint Server](/img/waypoint/get-started/gcp-waypoint-server.png)

</Tab>
</Tabs>


## Initialize Waypoint

Before you can build and deploy your application, you must initialize it with
the `init` command.

When you initialize Waypoint for your application, Waypoint first looks for 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 customize
for your application.

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.

### Explore `waypoint.hcl`

You will now explore the `waypoint.hcl` file to learn more about the
application's configuration.

In the `waypoint-examples/kubernetes/nodejs/` directory, run the following
command:

```shell-session
$ cat waypoint.hcl
```

The Terminal will show the contents of the `waypoint.hcl` file.

<Tabs>
<Tab heading="Docker Desktop" group="Docker">


```hcl
project = "example-nodejs"

app "example-nodejs" {
  labels = {
    "service" = "example-nodejs",
    "env"     = "dev"
  }

  build {
    use "pack" {}
    registry {
      use "docker" {
        image = "nodejs-example"
        tag   = "latest"
        local = true
      }
    }
  }

  deploy {
    use "kubernetes" {
      probe_path = "/"
    }
  }

  release {
    use "kubernetes" {
      load_balancer = true
      port = 3000
  }
}
```

</Tab>
<Tab heading="kind" group="kind">


```hcl
project = "example-nodejs"

app "example-nodejs" {
  labels = {
    "service" = "example-nodejs",
    "env"     = "dev"
  }

  build {
    use "pack" {}
    registry {
      use "docker" {
        image = "nodejs-example"
        tag   = "latest"
        local = true
      }
    }
  }

  deploy {
    use "kubernetes" {
      probe_path = "/"
    }
  }

  release {
    use "kubernetes" {
  }
}
```

</Tab>
<Tab heading="AWS EKS" group="EKS">


Notice how the build stanza in `waypoint.hcl` currently uses Docker. Waypoint
should use `aws-ecr` instead of `docker`. Replace the registry configuration
with `aws-ecr`, remember to replace the `region` with the region in which your
Kubernetes cluster is running, and `repository` with the name of the ECR
repository you created earlier. An example is shown below.

```hcl
project = "example-nodejs"

app "example-nodejs" {
  labels = {
    "service" = "example-nodejs",
    "env"     = "dev"
  }

  build {
    use "pack" {}
    registry {
      use "aws-ecr" {
        region     = "us-east-1"
        repository = "waypoint-example"
        tag        = "latest"
      }
    }
  }

  deploy {
    use "kubernetes" {
      probe_path = "/"
    }
  }

  release {
    use "kubernetes" {
      load_balancer = true
      port          = 80
    }
  }
}
```

</Tab>
<Tab heading="GCP GKE" group="GKE">


Be sure to edit the `image` value to match your GCP project name.

```hcl
project = "example-nodejs"

app "example-nodejs" {
  labels = {
    "service" = "example-nodejs",
    "env"     = "dev"
  }

  build {
    use "pack" {}
    registry {
      use "docker" {
        image = "gcr.io/<PROJECT-NAME-HERE>/example-nodejs"
        tag   = "1.0.0"
      }
    }
  }

  deploy {
    use "kubernetes" {
      probe_path = "/"
    }
  }

  release {
    use "kubernetes" {
      load_balancer = true
      port          = 80
    }
  }
}
```

</Tab>
</Tabs>


The `build` clause defines how Waypoint will build the application.

The `pack` option tells Waypoint to use the most relevant Cloud Native Buildpack
to build the application. Since this example application is written for NodeJS,
Waypoint will use NodeJS Buildpacks.

The `deploy` clause defines where Waypoint will deploy the application. The
`kubernetes` option tells Waypoint to deploy the application to Kubernetes.

The `release` stanza defines how our application will be released to our
environment. For example, in the case of external Kubernetes clusters this would
be where you would configure a `load_balancer` on a specific `port`.

With these configurations in place, execute the following command in order to
initialize Waypoint with this configuration.

```shell-session
$ waypoint init
```

## Build, deploy and release application

This application is configured to use Cloud Native Buildpacks to detect the type
of application running and to launch it within Kubernetes. Because Waypoint uses
the appropriate buildpack to create the Dockerfile, you do not need to create
the file yourself.

Once Waypoint completes a 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 application's artifacts.

For this example application, Waypoint will store the image in a remote Docker
repository after the application is built.

You can now deploy the application to Kubernetes by running `waypoint up`.

```shell-session
$ 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
```

-> **TIP**: 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.

-> **TIP**: 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.

```shell
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."

   Release URL: https://instantly-worthy-shrew.example.com
Deployment URL: https://instantly-worthy-shrew--v1.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. If the Deployment URL does
not respond, try the Release URL.

![Web application](/img/waypoint/get-started/web-app.png)

## 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 `views/pages/index.ejs` in your preferred development editor:

```shell-session
$ vi views/pages/index.ejs
```

Near `line 18`, change the text to anything that you like, such as today's date.

```html
<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.

```shell-session
$ 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 your modified text is running
in the application.



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](/tutorials/waypoint/get-started-install),
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](https://github.com/hashicorp/waypoint-examples). 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.

```shell-session
$ 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.

```shell-session
$ 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).

~> **NOTE**: Waypoint works best with Nomad 0.12.7 or later.

<Tabs>
<Tab heading="Local Development">


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

```shell-session
$ nomad agent -dev -network-interface="en0"
```

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

</Tab>
<Tab heading="Nomad Cluster">


See the [Nomad deployment
guide](/tutorials/nomad/production-deployment-guide-vm-with-consul) for
instructions on setting up a production Nomad cluster which can be used for this
tutorial.

You can also use the [Nomad git
repository](https://github.com/hashicorp/nomad/tree/master/terraform) or the
[Terraform starter
module](https://registry.terraform.io/modules/hashicorp/nomad-starter/aws/latest).

</Tab>
</Tabs>


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.

```shell-session
$ export NOMAD_ADDR='http://localhost:4646'
```

Throughout this tutorial, you can view the Nomad UI at
[localhost:4646](http://localhost:4646/ui/jobs).


### Setting up Nomad with Persistent Volumes

Waypoint installation on Nomad supports persistent data storage with host or csi volumes.
See [Nomad Stateful Workloads](https://learn.hashicorp.com/collections/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](https://docs.docker.com/config/daemon/ipv6/)

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:

```shell-session
$ waypoint install -platform=nomad -accept-tos -nomad-host-volume=<your_volume_name>
```

To install Waypoint with csi volume persistent storage, run:

```shell-session
$ waypoint install -platform=nomad -accept-tos -nomad-csi-volume-provider=<csi_driver_provider> -nomad-sci-volume-capaity-min=<bytes> -nomad-csi-volume-capacity-max=<bytes> -nomad-csi-fs=<file-stytem>
```

This tutorial shows installing a Waypoint server on Nomad with a host volume named "potato". Set up instructions [here](https://learn.hashicorp.com/tutorials/nomad/stateful-workloads-host-volumes?in=nomad/stateful-workloads).

```shell-session
$ waypoint install -platform=nomad -accept-tos -nomad-host-volume=potato

✓ Waypoint server ready
✓ 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
```

You can verify the successful installation of the Waypoint server by running
`nomad status`. You will observe the `waypoint-server`.

```shell-session
$ 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
```

Or, visit the [Nomad UI](http://localhost:4646/ui/jobs). You will observe the
`waypoint-server` job.

![Nomad server](/img/waypoint/get-started/nomad-install.png)

## 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:

```shell-session
$ cat waypoint.hcl
```

The Terminal will output the contents of the `waypoint.hcl` file.

```hcl
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`.

```shell-session
$ 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.

```plaintext
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.

![Web application](/img/waypoint/get-started/web-app.png)

You can also view the server side of the deployment in the [Nomad
UI](http://localhost:4646/ui/jobs).

![Nomad server](/img/waypoint/get-started/nomad-deploy.png)

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

```html
<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.

```shell-session
$ 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!


New to Waypoint?

Get Started

Introduction to Waypoint

Install Waypoint

Use Waypoint with Docker

Deploy an Application onto AWS Lambda

Deploy to the Cloud

Featured Content

Get Started - Kubernetes

Get Started - Nomad

All Waypoint Tutorials

AWS

Azure

Configuration

Get Started - Docker

Get Started - Kubernetes

Get Started - Nomad

Google Cloud

Looking for docs?

Infrastructure

Security

Networking

Applications

New to Waypoint?

Get Started

Introduction to Waypoint

Install Waypoint

Use Waypoint with Docker

Deploy an Application onto AWS Lambda

Deploy to the Cloud

Featured Content

Get Started - Kubernetes

Get Started - Nomad

All Waypoint Tutorials

AWS

Azure

Configuration

Get Started - Docker

Get Started - Kubernetes

Get Started - Nomad

Google Cloud

Looking for docs?