Waypoint enables you to execute commands in the context of a deployed application. This can be used to open up a shell for debugging, execute database migrations, and more.

Exec

Install and run Waypoint with this five minute quick start tutorial.

Getting Started with Waypoint

Getting Started

This page lists and defines technical terms used throughout Waypoint. Words such as "project", "app", etc. can be overloaded in the technical community, so this page attempts to clarify their meaning in the context of Waypoint.

Glossary

View a list of step-by-step tutorials for learning to deploy with Waypoint.

Documentation

Waypoint Overview

Waypoint app logs are aggregated and available to view via the CLI and UI.

Logs

Waypoint can be extended using custom plugins. Waypoint supports custom builders, deployment platforms, registries, release managers, and more.

Plugins

This page will outline some of the ideas we have for future versions of Waypoint. This is not an exhaustive list nor is it a promise that these features will be built, but it gives a glimpse into the vision we have for this project.

Roadmap

Waypoint is a work in progress, and this page provides tips for how to troubleshoot any issues that you might encounter while deploying applications.

Tips and Troubleshooting

Troubleshooting

Applications deployed with Waypoint will receive a public `waypoint.run` URL. This URL can be used to quickly view your deployed applications and share your applications with others.

Waypoint URL Service

URL Service

Workspaces are a mechanism to isolate multiple builds, deploys, etc. of the same applications. A common use case of workspaces are to provide environments for branch-based development, staging, etc.

Workspaces

The `app` stanza describes a single deployable application within a project. A majority of the configuration of your project will be done in this stanza.

app - waypoint.hcl

<code>app</code>

The `build` stanza describes how an application is built. During the build operation, Waypoint converts application source into an artifact and optionally pushes it to a remote registry.

build - waypoint.hcl

<code>build</code>

The `config` stanza configures [application configuration](/docs/app-config). Application configuration sets environment variables for your application that is either statically set or synced with an external system.

config - waypoint.hcl

<code>config</code>

The `deploy` stanza describes how an application is deployed. A deploy takes a previously built artifact and stages it onto the target deployment platform. The target deployment platform is pluggable and can be Docker, Kubernetes, Nomad, EC2, and more.

deploy - waypoint.hcl

<code>deploy</code>

The `hook` stanza configures hooks that are executed before or after operations. This can be useful to do things such as perform a security scan on an image, run database migrations on a deploy, etc.

hook - waypoint.hcl

<code>hook</code>

The `waypoint.hcl` file is used to configure each Waypoint project. It defines how Waypoint builds, deploys, and releases a project.

waypoint.hcl

The `plugin` stanza configures a plugin that will be used by the Waypoint configuration. This can set settings such as the checksum of the plugin, the kind of features the plugin supports, etc.

plugin - waypoint.hcl

<code>plugin</code>

The `registry` stanza configures the result of a build to be pushed to a registry such as a Docker Registry, Artifactory, etc. A registry is used to make the result of a build available to the deployment platform.

registry - waypoint.hcl

<code>registry</code>

The `release` stanza describes how an application is released. A release activates a previously staged deployment and opens it to general traffic. This step may involve adding a deployment to a load balancer, updating DNS, configuring a service mesh, etc.

release - waypoint.hcl

<code>release</code>

The `url` stanza configures the behavior of the [URL service](/docs/url) for the given application. This allows for certain applications to opt-out of the URL service, opt-in, etc.

url - waypoint.hcl

<code>url</code>

The `use` stanza specifies the name and configuration of a plugin to use for an operation.

use - waypoint.hcl

<code>use</code>

The `artifact` variable can be used to reference information about built artifacts. This can be used to access information such as the name and tag of a built Docker image, or the AMI of a built EC2 machine image.

artifact - Variables - waypoint.hcl

<code>artifact</code>

The `deploy` variable can be used to reference information about the deployment within a release. This can be used to access information such as the resulting instance ID, IP address, etc.

deploy - Variables - waypoint.hcl

The `entrypoint` variable contains important information about the Waypoint Entrypoint, such as the required environment variables that must be set for proper entrypoint behavior.

entrypoint - Variables - waypoint.hcl

<code>entrypoint</code>

The `waypoint.hcl` file uses HCL which is able to reference predefined variables. This section will document the list of available variables within the `waypoint.hcl`.

Variables - waypoint.hcl

Variables

Path variables are used to construct an absolute path to reference files or directories that may be used within your Waypoint configuration.

path - Variables - waypoint.hcl

<code>path</code>

Expressions are used to refer to or compute values within a configuration. The simplest expressions are just literal values, like `"hello"` or `5`, but the Waypoint configuration also allows more complex expressions such as arithmetic, conditional evaluation, and a number of built-in functions.

Expressions - Syntax - waypoint.hcl

Expressions

This page describes the syntax of the `waypoint.hcl` configuration language. The waypoint.hcl file uses either HCL or JSON, allowing both human and machine friendly formats. The recommended and typical format is HCL.

Syntax - waypoint.hcl

Syntax

Waypoint configuration is usually written in [HCL syntax](/docs/waypoint-hcl/syntax) which is designed to be relatively easy for humans to read and update. Waypoint also supports JSON. This syntax is useful when generating configurations programmatically, since existing JSON libraries can be used to prepare the generated configuration files.

JSON Syntax - waypoint.hcl

JSON Syntax

This page contains an automatically generated list of all the available functions within the Waypoint configuration file.

Full List - Functions - waypoint.hcl

Full Reference

The `waypoint.hcl` file uses HCL which is able to call predefined functions. Functions enable Waypoint configurations to represent complex configurations using programming techniques.

Functions - waypoint.hcl

Functions

Waypoint has a set of functions for templating strings, files, and directories with both predefined and custom variable values. These templates can use conditionals, loops, and more to dynamically generate content.

Templating - Functions - waypoint.hcl

Templating

Waypoint version compatibility is determined based on the protocol version and not the release version such as "1.2.3". Two different Waypoint release versions are compatible so long as their protocol versions are compatible.

Compatibility Promise

Waypoint is designed to be flexible and resilient when upgrading from one version to the next. We've carefully thought out an upgrade process so you can predict what will be involved when upgrading Waypoint.

Upgrading

This page shows the table of Waypoint versions alongside their protocol versions.

Protocol Version Table

Learn how to subscribe to notifications about future releases of Waypoint

Release Notifications

This upgrade guide describes any considerations for upgrading to Waypoint 0.2.0.

Version 0.2.0 - Upgrade Guide

Upgrade to 0.2.0

This section contains upgrade guides for specific Waypoint versions.

Version Upgrade Guides

Specific Version Guides

All connections to the Waypoint server via the CLI or UI require an auth token to authenticate.

Server Authentication

Authentication

Waypoint utilizes a server to enable collaboration with other team members, storing operation history, and enabling functionality such as logs, exec, and more.

Server

The recommended way to install the server is using the waypoint install command. This command will install a server into Docker, Kubernetes, or Nomad, bootstrap the server, and configure your local CLI to access that server. It is a single command to get up and running with Waypoint.

Running a Server

A Waypoint server needs to be maintained to ensure smooth operation and to protect against unexpected events such as server crashes. This page outlines various maintenance-related topics for smooth operation of a Waypoint server.

Server Maintenance

Maintenance

Waypoint Server in Production

Production

The Waypoint server must be secured accordingly. This section will outline the risks (and explicit non-risks) of a Waypoint server and mitigations the server may have towards these.

Server Security

Security

Lifecycle: Build

Build

A deploy takes a previously built artifact and stages it onto the target deployment platform. The target deployment platform is pluggable and can be Docker, Kubernetes, Nomad, EC2, and more.

Lifecycle: Deploy

Deploy

Hooks can be used to execute commands before or after any lifecycle operation.

Lifecycle: Hooks

Hooks

Waypoint has an opinionated view on the minimum application lifecycle: build, deploy, and release. These are the core elements that Waypoint orchestrates during a `waypoint up`.

Application Lifecycle

Lifecycle

A release activates a previously staged deployment and opens it to general traffic. This step may involve adding a deployment to a load balancer, updating DNS, configuring a service mesh, etc.

Lifecycle: Release

Release

Welcome to Waypoint! This introduction section covers what Waypoint is, the problem Waypoint aims to solve, and how Waypoint compares to other software.

Introduction

Helm is a package manager for Kubernetes. Waypoint is not a package manager. Waypoint is a tool for describing how to build, deploy, and release applications and providing a consistent workflow on top of that: `waypoint up`.

Waypoint vs. Helm

Helm

It can be difficult to understand how different software compare to each other. Is one a replacement for the other? Are they complementary? etc. In this section, we compare Waypoint to other software.

Waypoint vs. Other Software

Waypoint vs. Kubernetes

Kubernetes

Waypoint vs. PaaS systems such as Heroku, Vercel, etc.

Waypoint vs. PaaS (Heroku, Vercel, etc.)

Heroku, Vercel, etc.

Waypoint has many different components that interact with each other. This page documents all of these components: what they do, how they work with each other, when they're required, etc.

Architecture

This page documents how operations such as build, deploy, and release execute within Waypoint. This helps explain what components need access to what systems and how information flows within Waypoint.

Operation Execution

This section covers advanced technical details about the architecture of Waypoint.

Internals

Extending Waypoint

Initializing the SDK

Passing Values

Passing Values Between Components

Authenticator

Builder

ConfigurableNotify

Configurable

Default Parameters

Destroy

Plugin Interfaces

Platform

Registry

ReleaseManager

Implementing the Builder Interface

Compiling the Plugin

Handling Configuration

Creating an Example Application

Creating a Waypoint Plugin

Registering Plugin Components

Testing the Plugin

The entrypoint can be disabled by disabling build-time injection or by setting a runtime variable in already-built artifacts.

Disable the Entrypoint

Disable

Waypoint uses an entrypoint binary to enable features such as application configuration, logs, exec, and more.

Entrypoint

How to utilize Waypoint with CircleCI as the service to run
Waypoint to build and deploy applications

Integrating Waypoint with CircleCI

CircleCI

How to utilize Waypoint in a GitHub development workflow and
with GitHub Actions

Integrating Waypoint with GitHub Actions

GitHub Actions

How to utilize Waypoint in a GitLab development workflow and
with GitLab CI/CD

Integrating Waypoint with GitLab CI/CD

GitLab CI/CD

An overview of how to automate the execution of Waypoint in remote systems

Automating Execution of Waypoint

Automating Execution

How to utilize Waypoint with Jenkins as the service to run
Waypoint to build and deploy applications

Integrating Waypoint with Jenkins

Jenkins

Waypoint can sync application configuration values with external systems such as Kubernetes ConfigMaps, HashiCorp Vault, Amazon Parameter Store, and more. As the values change, Waypoint will automatically update your deployments and restart your application.

Dynamic Values - Application Configuration

Dynamic Values

Waypoint can configure your application via environment variables that are either set via static values or synced with an external system such as Kubernetes ConfigMaps, HashiCorp Vault, Amazon Parameter Store, etc.

»Upgrade Guides for Specific Versions