Use Waypoint with Docker

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.

Launch Terminal

This tutorial includes a free interactive command-line lab that lets you follow along on actual cloud infrastructure.

Start interactive lab

Prerequisites

You must install the waypoint binary installed locally 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 repository. Clone this repository on your computer to complete this tutorial.

Clone the Waypoint Examples repository.

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

$ cd waypoint-examples/docker/ruby

Install and run Docker Desktop

Install the most recent stable version of 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.

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

✓ 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. To learn more about Kubernetes, see the getting started guide for deploying an application to Kubernetes. The walkthrough shows you how to deploy the server and an example app to Kubernetes.

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.

$ cat waypoint.hcl

project = "example-ruby"

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

  build {
    use "pack" {}
  }

  deploy {
    use "docker" {}
  }
}

project = "example-java"

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

  build {
    use "pack" {}
  }

  deploy {
    use "docker" {}
  }
}

project = "example-nextjs"

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

  build {
    use "pack" {}
  }

  deploy {
    use "docker" {}
  }
}

project = "example-nodejs"

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

  build {
    use "pack" {}
  }

  deploy {
    use "docker" {}
  }
}

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.

Initialize Waypoint for the Example App

Run the init command to initialize the application.

$ waypoint init

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

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

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

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.

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

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.

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

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

$ 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!