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.
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.
Navigate to the docker/ruby
directory. Notice that the Docker example directory contains example applications in other programming languages as well.
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's output will indicate that the server container has started and that your local CLI is configured to communicate with it.
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.
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.
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 will initialize the application and output a message in the Terminal window.
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 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.
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.
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.
Open the following file in your preferred development editor:
app/views/welcome/index.erb
Find the line that says "app was deployed with Waypoint" and add today's date or any text.
Back in the Terminal, redeploy the application with your new and improved text.
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.