»Project Configuration: waypoint.hcl

The waypoint.hcl file is used to configure each Waypoint project. It defines how Waypoint builds, deploys, and releases a project. The waypoint.hcl file is written in HCL or JSON, allowing both human and machine friendly formats.

»waypoint.hcl Location

Waypoint expects one waypoint.hcl per project. The waypoint.hcl configuration can be a file committed alongside your project source, or it can be stored on the Waypoint server without modifying your version controlled source at all.

For any Waypoint operation such as waypoint up, Waypoint will always prefer a local waypoint.hcl file if it is found, even if the project is associated with a server-side configuration.

»File

The waypoint.hcl file may be committed as a file to version control. This allows the Waypoint behavior of a project to be versioned directly alongside the application. The downside of this approach is that it requires making changes to your project source.

For this approach, the waypoint.hcl file is typically placed at the root of a version control repository. To deploy multiple applications, define each with an app stanza.

When executing the waypoint CLI, it will search for the waypoint.hcl file in the current directory, followed by each subsequent parent directory.

»Server

The waypoint.hcl configuration may be stored on the Waypoint server and associated directly with a project.

The benefit of this approach is that no changes to project source repositories are required and the team managing the Waypoint configuration and the team using Waypoint can be easily separated.

This approach also makes it very easy to migrate existing applications to Waypoint, perhaps using a GitOps-style deployment pattern, since you can create and configure the projects completely in the web UI without having to touch any existing source code.

To store the waypoint.hcl configuration on the Waypoint server, specify the waypoint.hcl contents in the web UI when prompted or specify the -waypoint-hcl flag to the waypoint project apply command.

»Template waypoint.hcl

project = "project-name"

app "app-name" {
  path = "./src"

  build {
    # ...
  }

  deploy {
    # ...
  }

  release {
    # ...
  }

plugin "plugin-name" {

}

project = "project-name"
app "app-name" {  path = "./src"
  build {    # ...  }
  deploy {    # ...  }
  release {    # ...  }
plugin "plugin-name" {
}

»Placement Tables

Many pages within the waypoint.hcl documentation section will have a placement table just beneath the header. This table documents where a configuration, function, or variable may be used. An example placement table is shown below.

If the example below were present on the documentation page, the documented feature is only valid within the context of an app stanza. It is not valid at the top-level, or any further nested locations.

»Top-level

The "top-level" refers to the objects that are not nested in any other configuration. The top-level is made of "stanzas" and "parameters".

»Stanzas and Parameters

A "stanza" is a block of code that opens and closes with braces { } and may contain more configuration parameters. Above, app "app-name" {} is the app stanza.

A "parameter" is the term used to describe any configuration object. build and path are parameters of app. project, app "app-name", and plugin are parameters of the top-level.

Several "common" parameters can be used in stanzas. These are use and hook. These can not be top-level parameters, but are available in build, deploy, and release. These are documented further in their respective pages.

A stanza is a parameter, but not all parameters are stanzas.

»Variables

Waypoint configuration files have access to a number of predefined variables. Using variables helps make a Waypoint configuration more robust by more explicitly specifying paths, reducing duplication, etc. You can learn more about variables in the dedicated variables section.

»Top-level Parameters

»Required

• app (app) - One or more applications to build, deploy, and release with Waypoint.

• project (string) - The name of the project. This should be unique for the Waypoint server and must not be changed later. This is used to organize information on the server. This field is optional if you're using remote operations, including those triggered via Git polling.

»Optional

• plugin (plugin) - External plugins that may be used in this configuration. Plugins are implicitly defined with use stanzas so this is only required if you need to additionally configure a plugin.