chore(docs): reorganize getting-started section #2611

binarycat0 · 2025-09-18T18:22:08Z

add docs/getting-started/deploying-polaris section
- move docs/quickstart.md -> docs/getting-started/deploying-polaris/local-deploy.md
- move docs/getting-started/deploying-polaris -> docs/getting-started/deploying-polaris/cloud-deploy
- fix AWS typo in quickstart-deploy-azure.md, quickstart-deploy-gcp.md
add docs/getting-started/creating-a-catalog section sctructure
- Creating a Catalog
  - S3
    - AWS (TBD)
    - MinIO (MinIO example)
  - GCS (TBD)
  - Azure (TBD)
add docs/managing-security section
- move docs/access-control.md -> docs/managing-security/access-control.md
- move docs/external-idp.md -> docs/managing-security/external-idp/_index.md
- create keycloak-idp.md -> docs/managing-security/external-idp/keycloak-idp.md as _Keycloak IDP example
- add ref to ./keycloak-idp.md to docs/managing-security/external-idp/_index.md

Motivation:

The current structure of the getting-started section is somewhat inconvenient due to inconsistent menu ordering and section naming. For example, Quickstart doesn't reflect its actual content - it's essentially a Local Deployment guide. Additionally, right after the Quickstart section, we have examples of Deploying Polaris On Cloud Providers, followed immediately by a Polaris + MinIO usage example. Meanwhile, the important Using Polaris section is placed at the very end.

Goal:

In this PR, I propose a minor reorganization of the Getting Started section that will enable new users and contributors to learn the project documentation in a more natural and intuitive way.

Old documentation view:

New documentation view:

dimas-b

Thanks for your efforts on improving docs, @binarycat0 !

I have a somewhat radical comment below... I hope you do not mind refactoring the guides further :)

site/content/in-dev/unreleased/external-idp.md

site/content/in-dev/unreleased/getting-started/alternate-conf/_index.md

dimas-b · 2025-09-18T21:35:12Z

site/content/in-dev/unreleased/getting-started/using-polaris.md

using-polaris.md still assumes AWS when it talks about creating a catalog 🤔

I'd propose to break the getting started docs like this:

Installing Dependencies

Deploying Polaris

Local Deployment

Cloud Providers

AWS

GCP

Azure

Creating a Catalog

S3

AWS

MinIO

GCS

Azure

Using the Polaris Catalog (refer to the catalog created in the previous section)

The MinIO and other guides may have to be re-written without references to docker compose, just show docker instructions for MinIO, plus POLARIS CLI for creating the catalog.

Granted it's going to be a bit more work, but I hope the end result will be more user-friendly and will be easier to extend to new environments. WDYT?

The "Cloud Providers" getting started scripts actually do create a catalog as well. So maybe we don't need a new section on that. If we want to make the changes more consise, we may be able to make a reference to the create-catalog.sh script instead from within using-polaris.md, which takes care of all catalog creation.

Thanks for valuable comments! I will try to cover all in this PR 👌

@dimas-b will it be acceptable If I create the structure in this PR and create an extra Issue to cover the remaining later? Maybe by other volunteer.

Creating a Catalog

S3

AWS (TBD)

MinIO (done)

GCS (TBD)

Azure (TBD)

Please check new version 🙏

dimas-b

The new doc structure LGTM 👍 Thanks!

I think it would be nice to rework the MinIO guide a bit and populate catalog creation guides (you may need to refer to the example deployment scripts for each cloud technology).

dimas-b · 2025-09-19T14:39:41Z

site/content/in-dev/unreleased/getting-started/creating-a-catalog/_index.md

This section header is "clickable" in the left-hand pane, but the "Getting Stated" section is not (#2551)... Could you fix that too? I guess it's related to having render: never in the latter... Why don't we add some text to it and render it like all the other sections?

This can be done later, of course.

Yeah, the reason because of render: never. I will fix it.

dimas-b · 2025-09-19T14:45:02Z

site/content/in-dev/unreleased/getting-started/creating-a-catalog/catalog-azure.md

+weight: 300
+---
+
+TBD


I suppose the Defining a Catalog section from Using Polaris needs to move here (with minor changes for each specific cloud technology).

dimas-b · 2025-09-19T14:47:43Z

site/content/in-dev/unreleased/getting-started/creating-a-catalog/s3/catalog-aws.md

+weight: 100
+---
+
+TBD


It's more or less the same as MinIO, but you need to provide region and roleArn, but do not provide endpoint.

dimas-b · 2025-09-19T14:49:29Z

site/content/in-dev/unreleased/getting-started/creating-a-catalog/s3/catalog-minio.md

+weight: 200
 ---

 In this guide we walk through setting up a simple Polaris Server with local [MinIO](https://www.min.io/) storage.


My thinking was to just give instructions for "manual" setup in this guide (copy from the docker compose file) and may be link to the docker compose example at the end of the guide (with minimal text, just indicating that the docker compose file shows and end-to-end integration example for MinIO). WDYT?

Can we keep the current version? Using MinIO looks like not a standard path, so I would prefer to save it as is.

Without refactoring this page, the whole Getting Started reorg is not quite complete, IMHO... Still, I'd be ok with merging these doc changes "as is". I can probably make a follow-up PR from my side. I guess it's easier than going through GH comments 😅

I would appreciate it if you cover this part from your side 🙏

dimas-b · 2025-09-22T18:05:43Z

@binarycat0 : is this PR "ready for review" now? 🙂

dimas-b

Thanks for your work on this @binarycat0 ! From my POV this PR is good to merge with quick follow up (on my part) in mind.

If there are no objects from other reviewers, I'll merge and follow up later today.

dimas-b · 2025-09-22T23:33:01Z

Follow-up PR: #2652

binarycat0 · 2025-09-23T10:17:57Z

Thanks everyone for active support and suggestions. I believe the documentation will be much convenient to use with this new structure for new comers. Also, I understand there are much more things to do. 🚀

)

github-project-automation bot added this to Basic Kanban Board Sep 18, 2025

github-project-automation bot moved this to PRs In Progress in Basic Kanban Board Sep 18, 2025

binarycat0 marked this pull request as ready for review September 18, 2025 19:01

dimas-b reviewed Sep 18, 2025

View reviewed changes

binarycat0 marked this pull request as draft September 19, 2025 10:22

binarycat0 marked this pull request as ready for review September 19, 2025 13:39

dimas-b reviewed Sep 19, 2025

View reviewed changes

binarycat0 marked this pull request as draft September 22, 2025 15:09

binarycat0 force-pushed the chore/docs/reorganize-getting-started branch from c70ada2 to e84e46e Compare September 22, 2025 15:29

chore(docs): squash commits

8bda153

binarycat0 force-pushed the chore/docs/reorganize-getting-started branch from e84e46e to 8bda153 Compare September 22, 2025 15:34

binarycat0 added 4 commits September 22, 2025 16:43

chore(docs): fix doc links

14b4f9a

fix(enhancement): add catalog-azure example

3b18ee3

fix(enhancement): add creating-a-catalog docs

2816ec4

fix(enhancement): fix link

ce8445c

binarycat0 marked this pull request as ready for review September 22, 2025 18:56

dimas-b approved these changes Sep 22, 2025

View reviewed changes

github-project-automation bot moved this from PRs In Progress to Ready to merge in Basic Kanban Board Sep 22, 2025

dimas-b merged commit eb7618b into apache:main Sep 22, 2025
14 checks passed

github-project-automation bot moved this from Ready to merge to Done in Basic Kanban Board Sep 22, 2025

binarycat0 added a commit to binarycat0/polaris that referenced this pull request Sep 23, 2025

fix: fix broken markdown-link-check CI job after apache#2611 got merged

ce15df9

binarycat0 mentioned this pull request Sep 23, 2025

fix: fix broken markdown-link-check CI job after #2611 got merged #2655

Merged

snazy pushed a commit that referenced this pull request Sep 23, 2025

fix: fix broken markdown-link-check CI job after #2611 got merged (#2655

b1eb9bd

)

chore(docs): reorganize getting-started section #2611

chore(docs): reorganize getting-started section #2611

Uh oh!

Conversation

binarycat0 commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation:

Goal:

Old documentation view:

New documentation view:

Uh oh!

dimas-b left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dimas-b Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dimas-b left a comment

Choose a reason for hiding this comment

Uh oh!

dimas-b Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dimas-b commented Sep 22, 2025

Uh oh!

dimas-b left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dimas-b commented Sep 22, 2025

Uh oh!

binarycat0 commented Sep 23, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

binarycat0 commented Sep 18, 2025 •

edited

Loading

dimas-b Sep 18, 2025 •

edited

Loading

dimas-b Sep 19, 2025 •

edited

Loading