Waypoint can configure your application via environment variables via the CLI using `waypoint config`.

Application Configuration

Configuration

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 in 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 `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 build, 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>

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

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 application and providing a consistent workflow on top of that: `waypoint up`.

Waypoint vs. Helm

Helm

It can be difficult 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

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

»Waypoint vs. Other Software