📝 End-to-End Documentation for the New App Process

[julialawrence]

User Story

As an Analytical Platform Developer
I want to document the entire new app process, with a special focus on the sequential ordering of steps.
So that App Owners and Developers understand the critical order of operations, like creating the app in the Control Panel before setting up Cloud Platform namespaces, and then updating the app information with namespace and service account names to enable the new app to assume its role correctly.

Value / Purpose

This thorough documentation is essential to guide users through the new app process seamlessly, ensuring they follow the steps in the correct order to avoid common pitfalls and misunderstandings, thereby streamlining the app setup and deployment.

Useful Contacts

@data-platform-apps-and-tools

User Types

App Owners, App Developrs, New Users of the Analytical Platform

Hypothesis

If we provide detailed and clearly structured documentation outlining the step-by-step process for new app creation
Then users, especially App Owners, will find it easier to navigate the complexities of setting up new apps, leading to fewer errors, a smoother overall process and reduced support overhead.

Proposal

Documentation, potentially with illustrations published in AP User Guide.

Additional Information

High-level outine of the process available here: https://docs.google.com/document/d/1S9JfeeZyGTPIVORP29IU_5mgPMqV4A7LTEK51p6tZW4/edit

Definition of Done

• A complete set of documentation for the new app process, from start to finish, has been created
• Key steps are clearly outlined and ordered correctly, especially the sequence of creating an app in the Control Panel, setting up Cloud Platform namespaces, and updating app information with namespace names and service accounts
• The documentation has been reviewed and validated for accuracy and clarity by another team member who has carried out documentated process end-to-end
• Published in AP User Guide

[michaeljcollinsuk]

Initial thoughts:

1. Overview of steps to register an app
2. Create Repo (via template)
3. Register repo in Control Panel
   • AWS role created
   • Trust relationship updated to using namespace convention defined in docs
4. Create Cloud Platform PR for each required environment (e.g. dev) via CP cli
5. Go to Control Panel manage app page
6. Edit the AUTH_REQUIRED settings to True or False as required
7. Click button to create Auth0 client for your environment (as required)
8. Update auth settings e.g. IP allowlists (as required)
   • NOTE The Connections should not be publicly accessible (check this) - too sensitive/not relevant
9. Done!

[michaeljcollinsuk]

When the related documentation tickets have been completed, this should act as sufficient end-to-end documentation.
The documentation will be in the AP User Guidance.
All documentation steps should be run through by a member of the team before closing this ticket.

[michaeljcollinsuk]

Notes from initial run through of documentation https://docs.google.com/document/d/1yPU16spxcHkzLjCOnInc5hydc14LzXJEfWlB-Zvrc5A/edit

[michaeljcollinsuk]

Control Panel has been updated to add secrets in PR#1247.

Changes were made to ECR for the app runthrough, merged in this PR.

Testing these changes by reregistering the app via Control Panel in prod, and then rerunning the deploy workflow, resulted in the app being deployed successfully.

The new app template repo has been updated in a PR to remove steps from the github actions that are no longer required

Updated documentation based on notes from the initial runthrough - check the changes in the latest commit to the open PR

[michaeljcollinsuk]

Additional changes made to Control Panel in ministryofjustice/analytics-platform-control-panel#1250