June 20-22 Announcing HashiConf Europe full schedule: keynotes, sessions, labs & more Register Now
  • Infrastructure
    • terraform
    • packer
  • Networking
    • consul
  • Security
    • vault
    • boundary
  • Applications
    • nomad
    • waypoint
    • vagrant
  • HashiCorp Cloud Platform

    A fully managed platform to automate infrastructure on any cloud with HashiCorp products.

    • consul
    • terraform
    • vault
    • packerbeta
    Visit cloud.hashicorp.com
  • Overview
  • Tutorials
  • Docs
  • CLI
  • Plugins
  • Community
GitHub
Download
    • v0.8.x (latest)
    • v0.7.x
    • v0.6.x
    • v0.5.x
    • v0.4.x
    • v0.3.x
    • v0.2.x
    • v0.1.x
    • Overview
      • Overview
      • Helm
      • Heroku, Vercel, etc.
      • Kubernetes
  • Getting Started
    • Overview
    • Compatibility Promise
    • Protocol Version Table
    • Release Notifications
      • Overview
      • Upgrade to 0.2.0

    • Install
    • Externally Built Images
    • Building Container Images
    • Helm Deployment
    • YAML-Free Deployment
    • YAML Directory Deployment
    • Resource Status
    • ConfigMaps and Secrets

    • Overview
    • Git Integration
    • Remote Operations
    • Overview
    • Build
    • Deploy
    • Release
    • Hooks
    • Labels
    • Workspace and Label Scoping
    • Overview
      • Overview
      • Input Variables
      • External Data
      • artifact
      • deploy
      • entrypoint
      • labels
      • path
      • workspace
      • Overview
      • Full Reference
      • Templating
      • Overview
      • Expressions
      • JSON Syntax
    • app
    • build
    • config
    • deploy
    • hook
    • plugin
    • registry
    • release
    • runner
    • url
    • use
    • variable
  • URL Service
  • Logs
  • Exec
    • Overview
    • Dynamic Values
    • Files
    • Internal Values
    • Workspace and Label Scoping
    • Overview
      • Overview
      • OIDC
      • Overview
      • Maintenance
      • Production
      • Security
    • Express Server Install
    • Overview
    • Configuration
    • Profiles
    • On-Demand Runner
    • Additional Runners
  • Workspaces
  • Plugins
  • Triggers

    • Overview
      • Overview
      • Registering Plugin Components
      • Handling Configuration
      • Implementing the Builder Interface
      • Compiling the Plugin
      • Creating an Example Application
      • Testing the Plugin
    • Initializing the SDK
    • Passing Values Between Components
      • Overview
      • Authenticator
      • Configurable
      • ConfigurableNotify
      • Builder
      • Registry
      • Platform
      • ReleaseManager
      • Destroy
      • Status
      • Default Parameters
      • Overview
    • Overview
    • Disable
    • Overview
    • GitHub Actions
    • GitLab CI/CD
    • CircleCI
    • Jenkins
  • Troubleshooting
  • Glossary

    • Overview
    • Architecture
    • Operation Execution
  • Roadmap
Type '/' to Search

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

new-install

From here, you can click on the New project button to create a new Waypoint project.

new-project

Follow the instructions, and optionally enable connect a Git repository to the project.

project-created

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

github logoEdit this page

Using Waypoint

The best way to understand what Waypoint can enable for your projects is to give it a try.

Waypoint tutorials
Waypoint documentation
Tutorial

Get Started - Kubernetes

Build, deploy, and release applications to a Kubernetes cluster.

View
Tutorial

Introduction to Waypoint

Waypoint enables you to publish any application to any platform with a single file and a single command.

View

Waypoint is maintained by HashiCorp, Inc.

View Code of Conduct
DocumentationCLI ReferenceTutorialsIntegrations
All systems normal