Run an application on Elastic Container Service

Deploy Waypoint to AWS Elastic Container Service

Azure

Run an application on an Azure Container Instance

Deploy Waypoint to an Azure Container Instance

Use static and dynamic values in Waypoint applications.

Configuration

Use and change environment variables in your application.

Static Application Configuration

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 a Waypoint 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 a Waypoint Application to Nomad

Google Cloud

Deploy Waypoint to Google Cloud Run

Build, deploy, and release applications to any platform.

Docs

Commands

Plugins

Community


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.

<KatacodaToggleButton forceScenarioContentMode />

## Prerequisites

You must install the `waypoint` binary 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">


```hcl
project = "example-ruby"

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

  build {
    use "pack" {}
  }

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

</Tab>
<Tab heading="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">


```hcl
project = "example-nextjs"

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

  build {
    use "pack" {}
  }

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

</Tab>
<Tab heading="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.

```bash
$ 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`.

```bash
$ 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">


Open the following file in your preferred development editor:

`app/views/welcome/index.erb`

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


Open the following file in your preferred development editor:

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

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


Open the following file in your preferred development editor:

`pages/index.js`

</Tab>
<Tab heading="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 will also need to have a local copy of
the [Waypoint Examples
applications](https://github.com/hashicorp/waypoint-examples).

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


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

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


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](https://learn.hashicorp.com/tutorials/terraform/eks?in=terraform/kubernetes).

If you follow this tutorial, you will be properly configured to run commands
with `kubectl` against the cluster.

~> **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">


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](https://learn.hashicorp.com/tutorials/terraform/gke?in=terraform/kubernetes).

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


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


```shell-session
$ kubectl get all

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

</Tab>
<Tab heading="AWS 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">


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


```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="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">


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


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 will also need to
have a local copy of the [Waypoint Examples
repository](https://github.com/hashicorp/waypoint-examples).

### 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](https://learn.hashicorp.com/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).

## Install the Waypoint server

Run the following command to install the Waypoint server job to Nomad.

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

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


Get Started

Introduction to Waypoint

Install Waypoint

Use Waypoint with Docker

Deploy to the Cloud

Featured Content

All Waypoint Tutorials

Looking for docs?

Infrastructure

Security

Networking

Applications

Get Started

Introduction to Waypoint

Install Waypoint

Use Waypoint with Docker

Deploy to the Cloud

Featured Content

All Waypoint Tutorials

Looking for docs?