»Install Waypoint

Waypoint uses both a client and a server to build, deploy, and release applications. This functionality is all available from a single binary.

»Download the Binary

To install Waypoint, find the appropriate package on the releases site for your system and download it as a zip archive.

After downloading Waypoint, unzip the package. Waypoint runs as a single binary named waypoint. Any other files in the package can be safely removed and Waypoint will still function.

To make the binary available from anywhere on your system, you can either copy it into /usr/local/bin or add it to a different directory in your PATH. For instructions on how to do that, see Editing your Path.

$ cp ~/Downloads/waypoint /usr/local/bin

Validate the installation by running the waypoint command.

$ waypoint
Usage: waypoint [-version] [-help] [-autocomplete-(un)install] <command> [args]

Common commands:
    release      Release a deployment.
    up           Perform the build, deploy, and release steps for the app.
    build        Build a new versioned artifact from source.

»Pull the Latest Waypoint Server Image

»Install the Waypoint Server

In this step we will install the Waypoint server onto Nomad. This allows you to view the user interface, collaborate on deployments, and more.

Waypoint automatically creates the Nomad job for the Waypoint server. As this is behind an authenticated image repository currently, you should pull the latest Waypoint server image, and tag it locally by running the following commands:

$ docker login docker.pkg.github.com
$ docker pull docker.pkg.github.com/hashicorp/waypoint/alpha:latest
$ docker tag docker.pkg.github.com/hashicorp/waypoint/alpha:latest waypoint/server:local

This step will not be required once the beta completes.

After tagging the image locally, run the following command to install the Waypoint server.

 $ waypoint install -server-image=waypoint/server:local -platform=nomad --nomad-dc=dc1 -accept-tos


One of the functions of install is that it creates a context automatically that points to the newly created server with authentication. This is how Waypoint 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.

»Editing your Path (Optional)

If you do not want to copy Waypoint into a file already in your path, you can edit your PATH to include a directory that contains the Waypoint binary. This allows you to use the waypoint command without having to include the full directory path to the binary.

See what is in your current $PATH definition.

$ echo $PATH

If you do not have an entry for the Waypoint binary, add the following line to your shell profile:

export PATH=$PATH:my-directory-path-to-waypoint-binary

For example: export PATH=$PATH:~/enlistments/waypoint

  • To determine your shell, run echo $SHELL
  • If using Bash, use nano ~/.bash_profile to edit your Bash profile.
  • If using ZSH, use nano ~/.zshrc to edit your ZSH profile.

»Next Step

Getting Started: Initialize Waypoint