New Interested in participating in the HCP Waypoint Private Beta Program? Apply here
  • Infrastructure
    • terraform
    • packer
  • Networking
    • consul
  • Security
    • vault
    • boundary
  • Applications
    • nomad
    • waypoint
    • vagrant
  • HashiCorp Cloud Platform

    A fully managed platform to automate infrastructure on any cloud with HashiCorp products.

    • consul
    • terraform
    • vault
    • packerbeta
    Visit cloud.hashicorp.com
  • Overview
  • Tutorials
  • Docs
  • CLI
  • Plugins
  • Community
GitHub
Download
    • v0.8.x (latest)
    • v0.7.x
    • v0.6.x
    • v0.5.x
    • v0.4.x
    • v0.3.x
    • v0.2.x
    • v0.1.x
    • Overview
      • Overview
      • Helm
      • Heroku, Vercel, etc.
      • Kubernetes
  • Getting Started
    • Overview
    • Compatibility Promise
    • Protocol Version Table
    • Release Notifications
      • Overview
      • Upgrade to 0.2.0
      • Upgrade to 0.3.0
      • Upgrade to 0.4.0
      • Upgrade to 0.5.0
      • Upgrade to 0.6.0
      • Upgrade to 0.7.0
      • Upgrade to 0.8.0

    • Install
    • Externally Built Images
    • Building Container Images
    • Helm Deployment
    • YAML-Free Deployment
    • YAML Directory Deployment
    • Resource Status
    • ConfigMaps and Secrets

    • Overview
    • Git Integration
    • Remote Operations
    • Overview
    • Build
    • Deploy
    • Release
    • Hooks
    • Labels
    • Workspace and Label Scoping
    • Overview
      • Overview
      • Input Variables
      • External Data
      • artifact
      • deploy
      • entrypoint
      • labels
      • path
      • workspace
      • Overview
      • Full Reference
      • Templating
      • Overview
      • Expressions
      • JSON Syntax
    • app
    • build
    • config
    • deploy
    • hook
    • plugin
    • registry
    • release
    • runner
    • url
    • use
    • variable
  • URL Service
  • Logs
  • Exec
    • Overview
    • Dynamic Values
    • Files
    • Internal Values
    • Workspace and Label Scoping
    • Overview
      • Overview
      • OIDC
      • Overview
      • Maintenance
      • Production
      • Security
    • Express Server Install
    • Overview
    • Configuration
    • Profiles
    • On-Demand Runner
    • Additional Runners
  • Workspaces
  • Plugins
  • Triggers

    • Overview
      • Overview
      • Registering Plugin Components
      • Handling Configuration
      • Implementing the Builder Interface
      • Compiling the Plugin
      • Creating an Example Application
      • Testing the Plugin
    • Initializing the SDK
    • Passing Values Between Components
      • Overview
      • Authenticator
      • ConfigSourcer
      • Configurable
      • ConfigurableNotify
      • Builder
      • Registry
      • Platform
      • ReleaseManager
      • Destroy
      • Status
      • Default Parameters
      • Overview
    • Overview
    • Disable
    • Overview
    • GitHub Actions
    • GitLab CI/CD
    • CircleCI
    • Jenkins
  • Troubleshooting
  • Glossary

    • Overview
    • Architecture
    • Operation Execution
  • Roadmap

The Waypoint website is being redesigned to help you find what you are looking for more effectively.

Type '/' to Search

»Getting Started with Waypoint

It only takes a few minutes to get started with Waypoint on your local development environment. This quick start example uses Docker, either on Linux or with Docker Desktop for Windows and macOS. This will introduce you to the basics of Waypoint, even if your target environment is not Docker.

Afterwards, go in-depth with tutorials for AWS, Azure, GCP, Kubernetes, and Nomad at HashiCorp Learn. For detailed Kubernetes-focused documentation, see the dedicated Kubernetes section.

»Installing Waypoint

Download the Waypoint binary and install it to your system. The easiest way to install it is to use our official signed packages for Homebrew, apt, yum, and other package managers.

»Installing the Server

Start the Docker Desktop application.

Install the Waypoint server to Docker with the install command. The -accept-tos flag is required to use the waypoint.run URL publishing service.

$ waypoint install -platform=docker -accept-tos
$ waypoint install -platform=docker -accept-tos

When it completes, you'll see this message.

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

»Initializing Waypoint

Clone the git repository with Waypoint application examples, or download the code directly from GitHub.

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

Navigate to the docker/nodejs directory.

$ cd waypoint-examples/docker/nodejs
$ cd waypoint-examples/docker/nodejs

All the code you need is provided in this directory, including a waypoint.hcl configuration file that will deploy the application to Docker.

Run init to set up the project.

$ waypoint init
$ waypoint init

You'll see this output.

✓ Configuration file appears valid
✓ Local mode initialized successfully
✓ 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.
✓ Configuration file appears valid
✓ Local mode initialized successfully
✓ 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.

»Deploying

Now, run waypoint up to build, deploy, and release the application.

$ waypoint up
$ waypoint up

It may take a minute or two and then you'll see this output.

» Building...
✓ Creating pack client
✓ Building image
✓ Injecting entrypoint binary to image

Generated new Docker image: example-nodejs:latest

» Deploying...
✓ Setting up waypoint network
✓ Starting container
⠹ App deployed as container: example-nodejs-01EMM4TEN9SCXXE900F4EFQ9NR

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

           URL: https://instantly-worthy-shrew.alpha.waypoint.run
Deployment URL: https://instantly-worthy-shrew--v1.waypoint.run
» Building...
✓ Creating pack client
✓ Building image
✓ Injecting entrypoint binary to image

Generated new Docker image: example-nodejs:latest

» Deploying...
✓ Setting up waypoint network
✓ Starting container
⠹ App deployed as container: example-nodejs-01EMM4TEN9SCXXE900F4EFQ9NR

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

           URL: https://instantly-worthy-shrew.alpha.waypoint.run
Deployment URL: https://instantly-worthy-shrew--v1.waypoint.run

Visit either URL shown in the output. You will see a NodeJS application running on your local Docker Desktop instance.

Web application

»Changing

Change any part of the file at docker/nodejs/views/pages/index.ejs such as the <h1> tag at about line 18. Run up again to deploy a new version of the application.

$ waypoint up
$ waypoint up

You'll see a new URL that you can visit to view the latest version of the application.

»Debugging

Waypoint includes several sub-commands to help you monitor and debug your application.

Run logs to view Waypoint's logs. This may not include all of your application-specific logs, but will display Waypoint's logs.

waypoint logs
waypoint logs

The exec command connects you to a running instance of your application where you can examine the process list, run application-specific database upgrade commands, or do other debugging.

waypoint exec bash
# ps aux
waypoint exec bash
# ps aux

»Viewing the Web UI

Waypoint includes a web interface for viewing logs, deployments, builds, and other details. Launch it with the ui command.

waypoint ui -authenticate
waypoint ui -authenticate

Web User Interface

»Destroy

When you are done, run destroy to remove the application from Docker. Notice that the destroy command requires confirmation to run.

$ waypoint destroy -auto-approve
$ waypoint destroy -auto-approve

»Next Steps

You have used Waypoint to build, deploy, and release a NodeJS application to Docker.

For more detailed examples in many programming languages and on real cloud resources hosted at AWS, Azure, and GCP, visit HashiCorp Learn.

github logoEdit this page

Using Waypoint

The best way to understand what Waypoint can enable for your projects is to give it a try.

Waypoint tutorials
Waypoint documentation
Tutorial

Get Started - Kubernetes

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

View
Tutorial

Introduction to Waypoint

Waypoint enables you to publish any application to any platform with a single file and a single command.

View

Waypoint is maintained by HashiCorp, Inc.

View Code of Conduct
DocumentationCLI ReferenceTutorialsIntegrations
All systems normal