Deprecating projects (or how I learned to love apps)

Since the initial version of Waypoint, the product has supported the ability to configure multiple apps within a single waypoint.hcl file. Starting with Waypoint 0.9, this functionality is deprecated and will be removed in 0.10. The vast majority of users are not using this functionality and it served mostly as a source of confusion for users. For users who are using a monorepo pattern, we plan to add better workflows for you.

With a waypoint.hcl now focused on the configuration of a single application, the concept of a project within the Waypoint data model will be removed, moving applications to the top level. This is already how users talk about using Waypoint and we are confident that it will improve the overall understanding of Waypoint as well.

We’d love to hear your comments and concerns about this change below. We’re looking to incorporate the feedback into future planning work, such as ways to improve the monorepo pattern usage.


Hey @evanphx, we actually use the multi-app feature quite a bit with nomad-jobspec deploys. Is there a path forward for this?

For instance, we have one waypoint “app” config that manages the web app and another “app” config that launches a nomad “periodic” jobspec.

We also have another use-case that has many apps that get launched because the code is not multi-tenant. So, in this particular case, ‘n’ number of clients means ‘n’ number of apps.

I think the later case we could refactor into the nomad jobspec, but the first case needs two different jobspecs because “periodic” is defined at the job level.

Hi @dwanek!

Thanks for reaching out on this! Any chance you could share the waypoint.hcl files and maybe a short write up on your workflow?

We’ll absolutely figure out a way forward for ya.

Sure, I’ve done some name changing in the files, but the content is pretty much the same.

The first one I’m attaching is the one I mentioned with ‘n’ number of client apps. Upon waypoint up, the first app definition builds the image and pushes it to ECR. Subsequent app definitions use that same image via docker-pull.

waypoint-example-with-n-apps.hcl.txt (4.3 KB)

The second has a web app and two Nomad periodic job apps that get deployed. It also makes heavy use of dynamic stanzas that allow some differing configuration for each application. The build is similar to the one above where the first app builds the image and the other two use docker-pull to fetch it.

waypoint-example-with-periodic-jobs.hcl.txt (9.0 KB)

Thanks for any input. :purple_heart:


Similar to @dwanek, I was investigating migrating our Nomad deployment tooling to waypoint. Waypoint touts itself as having it’s projects map 1:1 with a VCS repository. In that case, it’s not clear to me how I would deploy multiple processes.

For a hypothetical python codebase with two processes:

  • web: python
  • worker: python

How would we specify that in waypoint now, given the deprecation of projects? The two processes are functionally the same app, just running two different processes. To me, it makes sense to at least have a project-level abstraction that ties both together.


We have been using Waypoint for our monorepo project, with a top-level ./waypoint.hcl that’s been working well for us. Having just tried to separate this into a waypoint.hcl per app (./app1/waypoint.hcl, ./app2/waypoint.hcl, etc.), a few comments:

  1. Seems we need to change directory to deploy multiple apps. Would be nice to have a replacement for “waypoint up -app app1” like “waypoint up -dir ./app1” that we can run from the VCS root directory. I thought “-p” might do this but seems it only relates to the server target. Perhaps I am missing something as fairly new to Waypoint.

  2. Similarly (but less importantly) something like “waypoint init -dir ./app1” would be nice instead of having to descend into each directory. Not clear how to use existing “-from-project” and “-into” when the application directory already exists.

  3. We did have a top-level config stanza for workspace-specific env vars shared between apps. It would be nice to be able to include these common definitions somehow in the app-level waypoint.hcl files.

  4. We also had been using a top-level variable stanza to declare input variables shared between apps. Thought having a shared var-file might help us out here, but the variable declarations also need to be shared.


Hello everyone!

Thanks again for providing feedback on the decision to remove multi-app workflows from Waypoint. We really appreciate you all taking the time to share your setups with us.

First off, we want to apologize for the hard failure that accompanied the the deprecation warning. Our intentions were to warn users with the message, but unfortunately it shipped as a config validation error instead. We will release a patch soon to update the deprecation warning and remove the error.

The team has taken your feedback into consideration and decided that we don’t want to remove multi-application orchestration from Waypoint just yet. We understand the power and value in orchestrating these applications easily without forcing users to deal with config sprawl or needing to write extra wrappers around Waypoint to orchestrate deploying multiple applications. We are exploring the possibility of disallowing the configuration of multiple applications within a single waypoint.hcl file but want to continue to enable multi-applications in Waypoint. We are very interested to hear how you all envision configuring multiple applications with Waypoint and develop our product in a way that can support your workflows.

Thank you!


Hey all -

We recently released a patch version of Waypoint (v0.9.1) today that removes the hard depreciation failure and sets it to a warning instead as intended. See the release post here: Waypoint v0.9.1 released. Thank you! <3

1 Like