Let's get serious about documentation, Hashicorp

Boundary
#1

I have a simple, serious question. How the heck do I install Boundary? Specifically, where in the docs is the external database created and the connection configured?

The table of contents does not make very much sense from a flow and direction perspective.

I’ve visited

  • Overview - nothing there
  • “Without Generated Resources” - what does this mean? There is discussion about initializing the database, but not connecting to an external one or setting it up.
  • Systemd install - nothing about there database
  • Postres Install - puzzling that there is literally no information there despite claiming to cover Postgres-specific installation requirements. It does have a link to HA install.
  • High Availability Install - this has some architecture components documented, but very feebly. Again, no mention of the database here other than in passing.

This has to be the most frustrating installation guide I’ve seen in an enterprise software offering. Providing something that clearly tells the story, then clearly strives to describe how it’s done, would help tremendously. What kind of a heading is “Without Generated Resources”? Has anyone UAT’d these instructions?

I apologize for the scathing review of the docs, but this is a paid, enterprise product for some, right? Does paid get different set of instructions - is this just bad by design to push to enterprise?

#3

For the controller there is a documentation entry concerning the connection to the database:

#4

It will be, in the future, but no, this is just OSS/best endeavours at the moment, as I understand it. Believe me, if you’d paid for Enterprise support in one of the four main products, you’d know it; it’s a completely different experience.

#5

Hi @aardvarq,

Sorry to hear you’re having trouble with the documentation. I’ll do my best to inline responses to your questions below:

To the first part of this question, we do our best in our installation section to outline installation procedures for the common Linux Systemd environment. This is a recommended installation example, and won’t cover all platforms. It purposefully doesn’t cover configuration of Boundary itself, that is covered in its own section.

To your second question, outside of dev mode, the operator is expected to run their own external database instance. Once that’s running, they can configure the database URL setting in the Boundary configuration to use it.

This is a great question, and I agree we don’t clearly point out what this means in the introduction to this section. In dev mode, Boundary generates resources as outlined in the getting started. Resources like a default user, a target, etc are created so folks can take boundary for a spin with minimal setup.

Outside of dev mode, generating these resources is optional as part of the database initialization step during installation.

I agree, we can make the heading on this section more clear. Thanks for proposing this change.

Boundary is free and open source software. We currently do not have a paid-for offering.

2 Likes
#6

Thanks for taking the time to answer my questions in detail. I really appreciate the help. As I go through my intallation, if I’ve got the time I’ll try to write up some additional how-to’s that might fit in to complement what’s been done.

As always, appreciate the work being done. Thank you kindly.