Projects

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.

Creating a Project

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 ready. The 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 waypoint.hcl here.

Web UI

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 project.

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.

waypoint init

If you have written a waypoint.hcl file, you can use the waypoint init command to initialize the project.

You must run this command in the same directory or in a child directory of the 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, specify the -update flag.

$ 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

Project initialized!

You may now call 'waypoint up' to deploy your project or
commands such as 'waypoint build' to perform steps individually.

waypoint project apply

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 \
   -data-source=git \
   -git-auth-type=ssh \
   -git-private-key-path=$HOME/.ssh/id_ed25519 \
   -git-url=git@github.com:hashicorp/waypoint-examples.git \
   example-project

Deploying a Project

Once a project is created and configured, you can now deploy the project.

If you have the repository checked out with a waypoint.hcl locally, 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.

Multiple Applications

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.