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

Use Waypoint with Docker

Warning

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

In this tutorial, you will learn how Waypoint works by deploying and running an application on your local machine with Waypoint and Docker Desktop.

Prerequisites

For this tutorial, you will need:

Clone the example repository

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

Clone the example repository.

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

Navigate to the example-app directory.

$ cd docker/example-app

Set up the Waypoint server

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

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

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

Set up an HCP organization and project

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

Enable HCP Waypoint

Click on the Waypoint option from the left navigation.

HCP UI with the Waypoint option highlighted

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

HCP Waypoint UI with the Activate Waypoint button highlighted

A dialog appears to confirm that Waypoint has been activated.

HCP Waypoint UI a dialog showing that Waypoint has been activated

Set up HCP Waypoint context

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

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

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

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

About the server workflow

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

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

Initialize Waypoint for the application

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

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

Review the waypoint.hcl file

Open the waypoint.hcl file.

docker/example-app/waypoint.hcl
project = "example-nodejs"

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

  build {
    use "pack" {}
  }

  deploy {
    use "docker" {}
  }
}

The app block defines the name of the application in Waypoint and contains the build, deploy, and release configuration blocks.

The labels block defines labels for the application. These are intended to contain information such as organizational or process data useful to the user but not directly interpreted by Waypoint.

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

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

  • Since the use "pack" option in this example is empty, Waypoint uses the default configuration for the Cloud Native Buildpacks plugin, which selects the most relevant pack to build the application.

The deploy block defines how Waypoint will deploy the app.

  • The use "docker" option in this example tells Waypoint to use the Docker plugin to deploy the application to Docker with any configurations defined in the block.

Waypoint URL service

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

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

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

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

Initialize Waypoint

Initialize Waypoint for the example application.

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

Project initialized!

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

Build and deploy

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

Run waypoint up

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

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

Start the Waypoint workflow.

$ waypoint up

Waypoint will start the process and output the following.

» Building example-nodejs...
✓ Running build v1

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

Generated new Docker image: example-nodejs:latest
✓ Running push build v1

» Deploying example-nodejs...
✓ Running deploy v1
✓ Setting up network...
✓ Starting container
✓ App deployed as container: example-nodejs-01GW2MQ3H43T5S077RHX0TPWMS
✓ Docker image "example-nodejs:latest" up to date!
✓ Finished building report for Docker platform
✓ Finished building report for Docker network resource
✓ Finished building report for Docker container resource
✓ All 2 resources are reporting READY

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

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

The deploy was successful!

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

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

Find the address of the example application by checking the running Docker containers on your local machine. This command lists the Docker containers, searches for the application name, and formats the output with the local address and application port.

$ docker container list --format "{{ .Image }} {{ .Ports }}" | \
    grep -i example-nodejs | \
    awk -F ' ' '{print $2}' | \
    cut -d"-" -f1 | \
    awk '{print "http://"$1}'

Open the formatted address from the output in your web browser.

http://0.0.0.0:59055

The example application showing deployment text

Update and redeploy the app

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

Open index.js in your text editor and update the deployment message. Save the file.

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

Navigate back to your terminal and restart the workflow.

$ waypoint up
✓ Running build v2

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

# ...

Generated new Docker image: example-nodejs:latest
✓ Running push build v2

» Deploying example-nodejs...
✓ Running deploy v2
✓ Setting up network...
✓ Starting container
✓ App deployed as container: example-nodejs-01GW2MQ3H43T5S077RHX0TPWMS
✓ Docker image "example-nodejs:latest" up to date!
✓ Finished building report for Docker platform
✓ Finished building report for Docker network resource
✓ Finished building report for Docker container resource
✓ All 2 resources are reporting READY

# ...

The deploy was successful!

# ...

Get the new deployment's URL and open it in your web browser. Note that the port is different from the first deployment as Waypoint randomizes the deployment's port.

$ docker container list --format "{{ .Image }} {{ .Ports }}" | \
    grep -i example-nodejs | \
    awk -F ' ' '{print $2}' | \
    cut -d"-" -f1 | \
    awk '{print "http://"$1}'

Open the formatted address from the output in your web browser and verify that it shows the change to the deployment message.

http://0.0.0.0:59055

The updated example application with new text

Next steps

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

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

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

Edit this page on GitHub