Review this walkthrough's prerequisites before installing 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 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
Because Waypoint is currently a pre-release private beta, you need to provide authentication details so that Docker can access the container image that contains the binary for running the Waypoint server. Once Waypoint is public, you will not need to do this step.
First, configure Docker authentication for accessing GitHub packages by following these steps.
Note: The Personal Access Token must have
read:packages permissions to be able to access the Docker repository.
Next, create a new Personal Access Token on GitHub, save it to a file, and then login to Docker.
$ cat ~/TOKEN.txt | docker login https://docker.pkg.github.com -u GITHUBUSERNAME --password-stdin
When you run
waypoint install, Waypoint will uses an image hosted on the GitHub Docker registry by default, and this secret will be used to authenticate to that registry.
Now you need to download the image so that we can start a container with it:
$ docker pull docker.pkg.github.com/hashicorp/waypoint/alpha:latest
»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.
$ waypoint install -platform=docker
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 app to Kubernetes. The walkthrough shows you how to deploy the server and an example app to Kubernetes.
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
$ echo $PATH
If you do not have an entry for the Waypoint binary, add the following line to your shell profile:
- To determine your shell, run
- If using Bash, use
nano ~/.bash_profileto edit your Bash profile.
- If using ZSH, use
nano ~/.zshrcto edit your ZSH profile.