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 Kubernetes can access the container image containing the binary for running the Waypoint server. Once Waypoint is public, you will not need to do this step.
In order to provide your Kubernetes cluster access to the Waypoint container image during the private beta, you need to create a Kubernetes secret that contains authentication information for the GitHub packages repository that hosts the image.
First, you need to create a personal access token on GitHub.
Note: The Personal Access Token must have
read:packages permissions to be able to access the Docker repository.
Then, save the token to a file named
TOKEN.txt. We will read this token when creating the Kubernetes secret. Ensure
is configured to interact with the correct Kubernetes cluster, and then run the following command:
$ kubectl create secret docker-registry github --docker-server=docker.pkg.github.com --docker-username=GITHUBUSERNAME --docker-password="$(< TOKEN.txt)" --docker-email=GITHUBEMAIL
When you run Waypoint install, it defaults to using an image hosted on the GitHub Docker registry.
»Install the Waypoint Server
In this step we will install the Waypoint server onto Kubernetes. This allows you to view the user interface, collaborate on deployments, and more.
Note: The Waypoint server image is currently hosted in GitHub Packages, which does not support containerd. If you are using Kind or K3d (which use containerd rather than DockerD), the Waypoint server install will fail with an ImagePullBackOff error. The Waypoint team is currently working on resolving this issue.
Run the following command to install the Waypoint server.
$ waypoint install -platform=kubernetes
In addition to Kubernetes, the Waypoint server can be installed on Docker or a Nomad cluster.
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.