We need a full deployment guide aimed at people who want to go to production with Parsec. It can reference some of the existing material, but it needs to be something that guides people through the process of installation, choosing the right back-end, choosing the right auth model, and finally validating that the installation is correct.
Details
This might be an opportunity to restructure the book a little bit as well. We currently have some really useful deployment materials, but they are scattered around, most notably in the "Parsec for Service Developers" section, which is not really the right place because people who want to successfully install/deploy/integrate Parsec are not necessarily people who actually want to do service development, in fact they typically wouldn't be.
The deployment guide should be a new page or possibly the main page of a new "Parsec Deployment Guide" chapter in the book. Existing pages that might then move into this chapter would include the secure installation steps, security recommendations and configuration guide.
The main page can and will reference other docs, but it can't just be a jumble of links. It needs to coach people through the process in a linear fashion.
Some things to include:
Installation, with some specialised info about Fedora and openSUSE where Parsec is a supported package. Show the installation commands for those systems. Reference the Yocto recipes for people who are creating Yocto images with Parsec. Finally, reference the existing secure installation guide for people who need to set up manually.
Advice on choosing the right back-end, and a reference to configuration steps.
Advice on choosing the right authenticator - pros and cons of using OS permissions to protect the socket, and help people to understand how Parsec will treat the incoming API calls from different apps or containers.
Show how to do parsec-tool ping, parsec-tool list-providers and parsec-tool list-authenticators with sample output, and explain that these can be used to validate that the expected configuration has taken effect.
Link to instructions for running end-to-end tests or any other relevant tests.
Definition of Done
Create first version of content - just needs PR review and merge. We will doubtless want to evolve this over time.
Summary
We need a full deployment guide aimed at people who want to go to production with Parsec. It can reference some of the existing material, but it needs to be something that guides people through the process of installation, choosing the right back-end, choosing the right auth model, and finally validating that the installation is correct.
Details
This might be an opportunity to restructure the book a little bit as well. We currently have some really useful deployment materials, but they are scattered around, most notably in the "Parsec for Service Developers" section, which is not really the right place because people who want to successfully install/deploy/integrate Parsec are not necessarily people who actually want to do service development, in fact they typically wouldn't be.
The deployment guide should be a new page or possibly the main page of a new "Parsec Deployment Guide" chapter in the book. Existing pages that might then move into this chapter would include the secure installation steps, security recommendations and configuration guide.
The main page can and will reference other docs, but it can't just be a jumble of links. It needs to coach people through the process in a linear fashion.
Some things to include:
parsec-tool ping,parsec-tool list-providersandparsec-tool list-authenticatorswith sample output, and explain that these can be used to validate that the expected configuration has taken effect.Definition of Done
Create first version of content - just needs PR review and merge. We will doubtless want to evolve this over time.