A project in Waypoint is a 1:1 mapping to a VCS repository (if one exists). A project can be comprised of one or more applications. Each application in a project represents a single thing that can be deployed. A project is the first thing you ever create after installing Waypoint.
Every project has an associated waypoint.hcl configuration. This configuration can be a file that is committed alongside the project in version control, or it can be stored on the server and associated with your project by name.
Depending on how a project is configured, it can be deployed through the local CLI, by clicking a button in the UI, triggered by changes in Git, or any mix of the aforementioned methods.
A project can be created in multiple ways. The recommended approach is via the web UI. Information about each approach is documented below.
In each approach, you'll have to have a waypoint.hcl configuration
waypoint.hcl configuration can be stored either alongside
your project's source or within the Waypoint server. You can find more
details about where to place the
When creating a new project through the UI, you can automatically log into the
dashboard by running
waypoint ui -authenticate on the CLI after installing Waypoint.
From here, you can click on the
New project button to create a new Waypoint
Follow the instructions, and optionally enable connect a Git repository to the project.
And there you have it! You are now ready to deploy a project using Waypoint! Read on to learn more about how to use a project once it has been created.
You must run this command in the same directory or in a child directory of
waypoint.hcl file. This will create and configure the project if it is
not already created. If you wish to update an already-existing project,
$ waypoint init
✓ Configuration file appears valid
✓ Connection to Waypoint server was successful
✓ Project "example-project" and all apps are registered with the server.
✓ Plugins loaded and configured successfully
You may now call 'waypoint up' to deploy your project or
commands such as 'waypoint build' to perform steps individually.
This is the most advanced and lowest level approach to creating or modifying
a project. The
waypoint project apply command
is a thin layer in front of the direct project API. You can use this command
to create or update a project:
$ waypoint project apply \
Once a project is created and configured, you can now deploy the project.
If you have the repository checked out with a
you can run
waypoint up and perform a local deploy. If your project was
configured to automatically poll a git repository, Waypoint
will automatically begin the process to build and deploy your application.
Most projects contain exactly one application. An example of a project with multiple applications may be a single repository that contains an "API" service and a "frontend" application in the same repository.
Organizations that follow a monorepo pattern may have many applications inside a single project. For monorepo users, a project MUST represent exactly one repository, but it does not have to represent a unique repository, so monorepo users may create multiple projects pointing to the same repository.
One simple example of this one-to-many pattern is the waypoint-examples
repository. The repository contains many Waypoint projects, and each project
in a sub-dir of the
waypoint-examples repo maps to this single repository.
Support for this is seen in the GitOps workflow, where a user specifies the parent repo to map to the project and can optionally specify a Git source path.