[New Content] - Overture Guides

MitchellShiell commented 5 months ago

Guide Content Updates

[x] Getting Started

Website Updates

[x] Repurpose Documentation template for guide content
- Issue: Guide content is displayed within our documentation site. This works for now as we develop the content. But we will need to figure out how/where to place these guides as the documentation pages have layout components not required for the guides (GitHub repo button, "${productName} Documentation" headers etc.).
  - Solution: Was actually fairly simple! I've updated the docs site with two turneries that will alter the header and github button if the sectionSlug !== "guides", all changes can be seen on this commit.
[x] Fix Hydration Error stemming from the docs SectionTableOfContents
- Issue: The navigation bar on the documentation site needs updating due to a documented hydration error that occurs when navigating between documentation pages with differing numbers of sidebar elements.
[x] Add copy to inform users of what to expect when running the quickstart
[ ] Make default documentation link behavior to open in a new tab
[x] Update Getting Started Page
[x] Update Documentation Overview Page
[x] Update Landing Page
[x] Update Product Page
[x] Remove references to DMS content
[x] Clean up getting started CSS
[x] Bonus: Add quickstart section to homepage
[x] Update Kafka and remove zookeepr

[!IMPORTANT] DMS Documentation: I am proposing that this update also replace the DMS documentation, updating all mentions of the DMS (ex., documentation and products page). When ready, the Overture Composer (quickstart) makes the most sense to replace all DMS CTAs, will be discussed further.

Related Demo Portal Updates

[x] Update links to guide content (Commit & link repo demoContent3)
[x] Remove mentions of DMS
[x] Update About this Portal CTA button (Commit & link repo demoContent3)
[x] Entry Modal update (Commit & link repo demoContent3)
[x] Fix downloads and update to file centric model

Content Review Cycle

Deployment Guide

[x] Personal Review
[x] Internal Review (Jon + Alexis)

Administration Guides

[x] Personal Review
[x] Internal Review (Edmund + Justin)

Submission Guide

[x] Personal Review
[x] Internal (Guanqiao + Brandon)

Download Guide

[x] Personal Review
[x] Internal Review (Guanqiao + Brandon)

Out of Scope for this update

Authorizing new users: Learn how to grant granular access to new users of your platform
Programmatic Downloads
Programmatic Submissions

MitchellShiell commented 4 months ago

The Introduction + OAuth commit includes:

Introduction explicitly stating who the guide is for, what is involved, and what they will need. Additionally includes disclaimer on specific deployment scenarios with a cta for personalized consultation as described in the top comment.
Running PostgreSQL image (keycloak-db) using the latest image, configured with environment variables for user credentials and database names. Each database service will use a separate volume for persistent data storage.
A pgAdmin4 service for managing the databases, configured with environment variables for login credentials and exposed on port 5051 of the host machine.
- With this setup when connecting databases into pgAdmin the host is the container name keycloak-db, username/password is admin/admin123 and the port is the default 5432 for both.
Running Keycloak with a breakdown of the keycloak specific command option flags.

[!NOTE] I am setting this up so Postgres databases do not have any exposed ports. All services here are connected to a custom network named db-network to isolate communication between services that need to interface with the databases (e.g., Song, Score, and Maestro). I believe this is standard practice to ensure databases on the back end are in an isolated and secure environment. Link to dockers documentation on networks top-level elements here

TO DO (inline with next commit):

[x] Update the Realm.json and User.json for Song and Score pre-configuration
[x] Provide download links, linked on the OAuth page

MitchellShiell commented 3 months ago

The Data Management + Search Portal commit includes:

Data Management deployment guide: Step-wise instructions with templated env files and detailed breakdowns for setting up Song, Score and their dependent services (Postgres, Minio, Kafka, and Zookeeper)
Search Portal deployment guide: Step-wise instructions with templated env files and detailed breakdowns for setting up Elasticsearch, Maestro, Arranger and Stage

[!NOTE] All configuration file links will need to be updated before merging to main. I will be using all the configuration files stored on the composer repo as they directly align, these will be need to be updated accordingly at time of publication.

TO DO (Will update on a later commit)

[x] Step-wise review alongside the composer (I suspect typos and small updates will be required)
[x] Make sure there is enough context/information at the beginning of each and microservice section

MitchellShiell commented 3 months ago

Data Submission + Download commit

Partial completion of data submission using the CLI
Partial completion of data download using the CLI
Created guide landing page with TOC _ quickstart instructions
Updated all introductory content with consistent CTA boxes and a getting started instructions for the Quickstart

Looking for input on programmatic data submission and download topics, will post linked issue!

MitchellShiell commented 3 months ago

Review Delegation

Instructions: Please provide your feedback with comments and suggestions on the file in repo link. We are aiming to publish Monday, so having your review in by end of Friday will be ideal!

If running the quickstart use the develop branch

git clone -b develop https://github.com/overture-stack/composer.git

docker compose up --attach conductor

[x] @leoraba please review the following, and tick here when complete (Instructions at top)

Netlify Link File in Repo

Deployment Guide: Authorization oauth.md

Netlify Link	File in Repo
Deployment Guide: Authorization	oauth.md