June 20-22 Announcing HashiConf Europe full schedule: keynotes, sessions, labs & more Register Now
  • 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

    • 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
      • 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
Type '/' to Search

»Tips and Troubleshooting

»Remove the Waypoint Server

The Waypoint Server creates several resources in Docker and Kubernetes that should be removed to either reinstall Waypoint or to completely remove it from a system.

Run waypoint destroy on your workspaces prior to removing the server to prevent hanging resources.

»Uninstall

Starting in 0.2.1, the server uninstall command will remove the server and supporting containers and services that are created via install. By default, it also creates a snapshot and deletes the server context.

For Docker, uninstall removes the Waypoint server-specific volumes, but refrains from doing a global volume prune. If you created deployments with Waypoint, there will likely be volumes left over from those deployments. You can remove these volumes individually, or globally via:

$ docker volume prune -f
$ docker volume prune -f

If the uninstall fails, see below for manual removal.

»Manual removal

»Waypoint Server in Docker

Ensure that you have the latest hashicorp/waypoint Docker image.

$ docker pull hashicorp/waypoint:latest
$ docker pull hashicorp/waypoint:latest

waypoint install for Docker creates a container and a volume. These resources should be removed when Waypoint Server is no longer needed. These are some example docker commands that should clean up after a Waypoint Server installation.

$ docker stop waypoint-server
$ docker rm waypoint-server
$ docker volume prune -f
$ docker stop waypoint-server
$ docker rm waypoint-server
$ docker volume prune -f

»Waypoint Server in Kubernetes

waypoint install for Kubernetes creates a StatefulSet, Service and PersistentVolumeClaim. These resources should be removed when Waypoint Server is no longer needed. These are some example kubectl commands that should clean up after a Waypoint Server installation.

$ kubectl delete statefulset waypoint-server
$ kubectl delete pvc data-waypoint-server-0
$ kubectl delete svc waypoint
$ kubectl delete statefulset waypoint-server
$ kubectl delete pvc data-waypoint-server-0
$ kubectl delete svc waypoint

»Pack Builder No Such Image

If the pack builder exits during build with an error similar to:

» Building...
Creating new buildpack-based image using builder: heroku/buildpacks:18
...
! failed to create 'detector' container: Error response from daemon: No such
  image: pack.local/builder/6c647962686577687270:latest
» Building...
Creating new buildpack-based image using builder: heroku/buildpacks:18
...
! failed to create 'detector' container: Error response from daemon: No such
  image: pack.local/builder/6c647962686577687270:latest

You may need to remove the Docker volumes that are responsible for storing cached images for pack.

$ docker volume list
...
$ docker volume list
...

Locate the volumes named starting with pack-cache- and remove them with docker volume rm.

»Investigating Deployed Applications

Waypoint includes several commands to support debugging and monitoring while developing your application.

»Exec Into the Application Container

After deploying your application, you can use waypoint exec to run commands in the context of the most recent deployment. Typically, waypoint exec will be used for running database migrations and debugging. However, you can use it for any purpose.

Use the exec command to open a shell prompt.

$ waypoint exec /bin/bash
$ waypoint exec /bin/bash

Since you are in the deployment directory, you will observe that Waypoint automatically executes against the currently deployed application.

From within the Docker container, validate that this is the actual application by listing out the directory hosting the application's compiled files. For example, if you used the pack builder this directory will be /workspace.

$ cd / && ls
$ cd / && ls

You should observe an output that contains the file structure for the current deployment.

List the processes that are running in the container.

$ ps aux
$ ps aux

Type exit to leave the interactive Docker session.

$ exit
$ exit

»View Waypoint Application and Entrypoint Logs

In the application's directory, run the logs command to observe the running logs for your deployment. This will include logs from the entrypoint if it is in use.

$ waypoint logs
$ waypoint logs

You will observe output similar to the following. These logs are from the existing deployment.

2020-09-24T06:20:18.162Z 2MGFF4:
2020-09-24T06:20:18.163Z 2MGFF4: > node-js-getting-started@0.3.0 start /workspace
2020-09-24T06:20:18.163Z 2MGFF4: > node index.js
2020-09-24T06:20:18.163Z 2MGFF4:
2020-09-24T06:20:18.383Z 2MGFF4: Listening on 3000
2020-09-24T06:20:18.162Z 2MGFF4:
2020-09-24T06:20:18.163Z 2MGFF4: > node-js-getting-started@0.3.0 start /workspace
2020-09-24T06:20:18.163Z 2MGFF4: > node index.js
2020-09-24T06:20:18.163Z 2MGFF4:
2020-09-24T06:20:18.383Z 2MGFF4: Listening on 3000

Press Ctrl-C to exit the logs command.

You may increase the verbosity of entrypoint logs by setting the WAYPOINT_LOG_LEVEL environment variable. See the documentation on entrypoint logs for more information.

»Access the Waypoint web UI

The Waypoint server includes a web-based user interface that you can use to view builds, deployments, and releases for projects and applications.

The web UI requires authentication. Run a single command to automatically open the browser and authenticate your session. This command will work if a graphical web browser is available on the machine where the command is being run.

$ waypoint ui -authenticate
$ waypoint ui -authenticate

NOTE: Waypoint currently uses self-signed certificates for TLS. Your web browser will require you to bypass a certificate warning to use the UI.

Review the application metadata and associated operations and logs in the browser.

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