Tips and Troubleshooting
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.
waypoint destroy on your workspaces prior to removing the server to prevent hanging resources.
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.
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
If the uninstall fails, see below for manual removal.
Ensure that you have the latest
hashicorp/waypoint Docker image.
$ 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
waypoint install for Kubernetes installs the Waypoint Helm chart to your Kubernetes cluster.
To delete the resources created by the Helm chart installation, the commands below will help with
the cleanup of the server and static runner:
$ helm uninstall waypoint $ helm uninstall waypoint-static $ kubectl delete pvc data-waypoint-server-0 $ kubectl delete pvc data-default-waypoint-static-runner-0
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
You may need to remove the Docker volumes that are responsible for storing cached images for pack.
$ docker volume list ...
Locate the volumes named starting with
pack-cache- and remove them with
docker volume rm.
If your Waypoint operation fails, task introspection can help troubleshoot the issue. Logs from the on-demand runner may not be readily available from the platform in which the runners are launched, and task introspection can get the information needed to troubleshoot.
In the example below, after a build failure,
waypoint task inspect was used
with the task ID. The Run Job results show that there was an error with the Docker
plugin which required arguments which were missing:
waypoint task inspect 01G669RE32WM0JBBGZW3JETYSJ » On-Demand Runner Task Configuration Task ID: 01G669RE32WM0JBBGZW3JETYSJ Task State: STOPPED Workspace: default Project: example-go Application: example-go » Run Job Configuration Job Configuration: Job ID: 01G669RE30ND9SKP50RYWP1B5H Operation: Build Target Runner: 01G669RE300HV2D1QPSYMSKHP2 Workspace: default Project: example-go Application: example-go Job Results: State: Error Complete Time: 33 minutes ago Error Messsage: There was an error while executing a Waypoint plugin for this operation! One or more required arguments for the plugin was not satisfied. This is usually due to a missing or incompatible set of plugins. For example, only certain build plugins are only compatible with certain registries, and so on. Please inspect the missing argument, the set of plugins you are using, and the documentation to determine if your plugin combination is valid. Plugin function: github.com/hashicorp/waypoint/builtin/pack.(*Builder).BuildODR-fm ==> Missing arguments: - docker.AccessInfo » Watch Job Configuration Job Configuration: Job ID: 01G669RE32M1MGQBYAVND110SS Operation: WatchTask Target Runner: * Workspace: default Project: example-go Application: example-go Job Results: State: Success Complete Time: 33 minutes ago » Start Job Configuration Job Configuration: Job ID: 01G669RE32M558VJZKRGYQ9W3S Operation: StartTask Target Runner: * Workspace: default Project: example-go Application: example-go Job Results: State: Success Complete Time: 33 minutes ago » Stop Job Configuration Job Configuration: Job ID: 01G669RE32HSPGP4AXDSA0NZ7S Operation: StopTask Target Runner: * Workspace: default Project: example-go Application: example-go Job Results: State: Success Complete Time: 33 minutes ago
Investigating Deployed Applications
Waypoint includes several commands to support debugging and monitoring while developing your application.
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.
exec command to open a shell prompt.
$ 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
$ 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
exit to leave the interactive Docker session.
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
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: > firstname.lastname@example.org 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
Ctrl-C to exit the
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.
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
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.