---
layout: docs
page_title: 'waypoint.hcl'
description: |-
  The `waypoint.hcl` file is used to configure each Waypoint project. It defines how Waypoint builds, deploys, and releases a project.
---

# 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](/docs/waypoint-hcl/syntax) or [JSON](/docs/waypoint-hcl/syntax/json),
allowing both human and machine friendly formats.

## `waypoint.hcl` Location

Waypoint expects one `waypoint.hcl` per [project](/docs/projects).
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`][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](/docs/projects).

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`](/commands/project-apply)
command.

## Template `waypoint.hcl`

```hcl
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.

<Placement groups={[['app', 'build']]} />

## 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](/docs/waypoint-hcl/variables).

## Top-level Parameters

### Required

- `app` <code>([app][app])</code> - 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](/docs/projects/remote), including those
  triggered via [Git polling](/docs/projects/git).**

~> **Warning: the project name can not be changed.** Changing the project
name is not currently supported. If you change the name, the history,
deployments, etc. of the previous project name will not be migrated or destroyed.
A future version of Waypoint will enable renaming projects.

### Optional

- `plugin` <code>([plugin][plugin])</code> - External plugins that may be
  used in this configuration. Plugins are implicitly defined with
  [`use`](/docs/waypoint-hcl/use) stanzas so this is only required if you
  need to additionally configure a plugin.

[app]: /docs/waypoint-hcl/app 'App Stanza'
[plugin]: /docs/waypoint-hcl/plugin 'Plugin Stanza'
