Skip to content

docs: Add quickstart documentation#2976

Merged
dimas-b merged 6 commits intoapache:mainfrom
adam-christian-software:adam-christian-1590-1
Nov 6, 2025
Merged

docs: Add quickstart documentation#2976
dimas-b merged 6 commits intoapache:mainfrom
adam-christian-software:adam-christian-1590-1

Conversation

@adam-christian-software
Copy link
Contributor

@adam-christian-software adam-christian-software commented Nov 4, 2025 •
edited
Loading

Context

I wanted to ensure that onboarding was very simple for users to play around with Polaris through a quickstart that does everything for you.

To that end, this is a quick_start docker compose file that will allow a user to auto-create a catalog, principal, privileges, etc and uses a MinIO-based connection. The Docker Compose file does not use any other scripts within the repository, so the user-facing documentation can be a one-line bash script.

There are no tests related to this as it is a getting started file.

Checklist

  • 🛡️ Don't disclose security issues! (contact [email protected])
  • 🔗 Clearly explained why the changes are needed, or linked related issues: Fixes #
  • 🧪 Added/updated tests with good coverage, or manually tested (and explained how)
  • 💡 Added comments for complex logic
  • 🧾 Updated CHANGELOG.md (if needed)
  • 📚 Updated documentation in site/content/in-dev/unreleased (if needed)

Docs Pics

image image

Console Output

image

@github-project-automation github-project-automation bot moved this to PRs In Progress in Basic Kanban Board Nov 4, 2025
snazy
snazy reviewed Nov 4, 2025
View reviewed changes
@snazy
Copy link
Member

snazy commented Nov 4, 2025

Meh, forgot to mention:
This one is really great for people to try out Polaris without having to run a lot of manual steps!

@adam-christian-software adam-christian-software changed the title docs(1590): Add quickstart documentation docs: Add quickstart documentation Nov 4, 2025
adutra
adutra reviewed Nov 5, 2025
View reviewed changes
Copy link
Contributor

@adutra adutra left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is really amazing, a complete no-brainer 😆

adutra
adutra reviewed Nov 5, 2025
View reviewed changes
@github-project-automation github-project-automation bot moved this from PRs In Progress to Ready to merge in Basic Kanban Board Nov 5, 2025
adnanhemani
adnanhemani approved these changes Nov 5, 2025
View reviewed changes
Copy link
Contributor

@adnanhemani adnanhemani left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is super great for reintroducing Quickstart! Thank you so much for doing this :)

I'm personally not a big fan of using MinIO here, as it may give off an (incorrect) impression that we are preferring a vendor/product for usage with Polaris. Using the local file based approach avoids all of that. But I also see the discussion in the PR regarding this topic, so I don't want to block on that. The usefulness of this PR far outweighs any negatives here!

@dimas-b dimas-b merged commit 94f6cb6 into apache:main Nov 6, 2025
15 checks passed
@github-project-automation github-project-automation bot moved this from Ready to merge to Done in Basic Kanban Board Nov 6, 2025
@adam-christian-software adam-christian-software deleted the adam-christian-1590-1 branch November 6, 2025 15:01
@adam-christian-software
Copy link
Contributor Author

adam-christian-software commented Nov 6, 2025

This is super great for reintroducing Quickstart! Thank you so much for doing this :)

I'm personally not a big fan of using MinIO here, as it may give off an (incorrect) impression that we are preferring a vendor/product for usage with Polaris. Using the local file based approach avoids all of that. But I also see the discussion in the PR regarding this topic, so I don't want to block on that. The usefulness of this PR far outweighs any negatives here!

Yeah, @adnanhemani , that's a good point and I agree. Let me list out some shared values that I think we have:

  1. We want end users to easily spin up Polaris. The one-line change idea does that.
  2. We want the quickstart to be aligned with what the common user scenarios are. Anecdotally, I have seen a lot of users on the Slack channel like these sort of S3-compatible sources.
  3. We want to be open-source first. Supporting Apache projects should be first option.
  4. Supporting or giving the impression that we are providing a closed-source vendor is NOT what we want.

I believe that there are two conflicting ideas here:

  1. We do NOT want to expose file-based object stores. A file-based approach would expose this to users and, in my opinion, the file-based object stores are only for local development and integration testing. They feel more akin to a "developer thing" rather than a "end user thing." Given that our easy onboarding goal is targeting end users, I would hope that we would not want to expose file stores.
  2. On the other hand, you are right that MinIO has done some recent actions which seems to be less than open-source first. That being said, I have not found another option which is open-source first. We thought about Apache Ozone (https://ozone.apache.org/), but we ruled that out as we did not want to build on the Hadoop ecosystem. If you have other ideas, I'd love to chat!

@dimas-b
Copy link
Contributor

dimas-b commented Nov 6, 2025

Polaris docs have a variety of options for storage: https://polaris.apache.org/in-dev/unreleased/getting-started/creating-a-catalog/

Getting Started should focus on simplicity, in which case MinIO appears to be the best fit. Given that MinIO (still) has public docker images, I believe it is fine to use it for getting-started guides.

snazy added a commit to snazy/polaris that referenced this pull request Nov 20, 2025
@snazy @binarycat0
@renovate-bot @adam-christian-software @adutra @dimas-b @XN137
Dremio merge 2025 11 07 17 08 (apache#157)
6d90d24 
* chore(enhancement): rename python package to apache-polaris (apache#2812)

- reorganize python package catalogs
- union all submodules (cli, polaris) under apache_polaris module
- put polaris generated context into apache_polaris/sdk
- make apache_polaris as a main module

* Update dependency pip-licenses-cli to v3.0.1 (apache#2996)

* docs: Add quickstart documentation (apache#2976)

* Add quickstart documentation targeting CLI convenience

Co-authored-by: Alexandre Dutra <[email protected]>

* Update dependency io.quarkus to v3.29.1 (apache#2985)

* Add getting started docs for Apache Ozone (apache#2989)

Closes apache#2207

* Add note on appendConfigOption Helm template explaining its logic (apache#2995)

This has come up a few times as the logic is a bit surprising for people familiar with Helm templates.

* fix(deps): update dependency io.micrometer:micrometer-bom to v1.16.0 (apache#3001)

* chore(deps): update quay.io/keycloak/keycloak docker tag to v26.4.4 (apache#3002)

* fix(deps): update dependency io.smallrye.common:smallrye-common-annotation to v2.14.0 (apache#3003)

* NoSQL: Add Mongo database backend (apache#2992)

* NoSQL: Add Mongo database backend

This change adds the MongoDB specific `MongoDbBackend` implementation. Test cases inherited from the database agnostic `AbstractPersistenceTests` for `Backend` implementations, running against a testcontainer running Mongo.

* bump mongo container version

* NoSQL: "standalone" `Persistence` configuration helper (apache#2993)

This change adds a utility module used in follow-up PRs like JMH based micro-benchmarks and correctness-tests, running as "standalone" JVMs providing flexible configurability via explict smallrye-config usage. This allows running JMH and correctness tests against various deployment scenarios, even multi-node database backends without having to spin up a full server instance. In other words: targeted benchmarking and testing eliminating side effects potentially induced by other components.

* NoSQL: Docker-compose example for customized testing (apache#2994)

* NoSQL: Docker-compose example for customized testing

Upcoming PRs bring JMH based benchmarking and correctness testing. This change adds a docker-compose on how to spin up a 3 node MongoDB instance useable for the mentioned benchmarks/tests.

* fix(deps): update dependency com.google.errorprone:error_prone_core to v2.44.0 (apache#3004)

* Make CallContextCatalogFactory request-scoped (apache#2972)

note the only non-test usage spot is `IcebergCatalogHandler#initializeCatalog`
and `IcebergCatalogHandler` is getting created by `IcebergCatalogAdapter`
which is already `@RequestScoped`.

* Last merged commit 6546689

---------

Co-authored-by: Artur Rakhmatulin <[email protected]>
Co-authored-by: Mend Renovate <[email protected]>
Co-authored-by: Adam Christian <[email protected]>
Co-authored-by: Alexandre Dutra <[email protected]>
Co-authored-by: Dmitri Bourlatchkov <[email protected]>
Co-authored-by: Christopher Lambert <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@snazy snazy snazy left review comments

@adutra adutra adutra approved these changes

@dimas-b dimas-b dimas-b approved these changes

+1 more reviewer

@adnanhemani adnanhemani adnanhemani approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@adam-christian-software @snazy @dimas-b @adutra @adnanhemani