docs: Add quickstart documentation (#2976)

adam-christian-software · adutra · web-flow · commit 94f6cb6de60f · 2025-11-06T10:01:47.000-05:00
* Add quickstart documentation targeting CLI convenience

Co-authored-by: Alexandre Dutra &lt;adutra@apache.org&gt;
diff --git a/README.md b/README.md
@@ -40,7 +40,7 @@ for contribution guidelines.
 Click [here](https://polaris.apache.org/in-dev/unreleased/) for a quick overview of Polaris.
 
 ## Quickstart
-Click [here](https://polaris.apache.org/in-dev/unreleased/getting-started/install-dependencies/) for the quickstart experience, which will help you set up a Polaris instance locally or on any supported cloud provider.
+Click [here](https://polaris.apache.org/in-dev/unreleased/getting-started/quick-start/) for the quickstart experience.
 
 ## Project Structure
 
diff --git a/getting-started/quickstart/README.md b/getting-started/quickstart/README.md
@@ -0,0 +1,22 @@
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# Apache Polaris Quickstart
+
+Please see the [quickstart guide](../../site/content/in-dev/unreleased/getting-started/quick-start.md) for more information.
diff --git a/getting-started/quickstart/docker-compose.yml b/getting-started/quickstart/docker-compose.yml
@@ -0,0 +1,259 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+services:
+
+  minio:
+    image: quay.io/minio/minio:latest
+    ports:
+      # API port
+      - "9000:9000"
+      # UI port
+      - "9001:9001"
+    environment:
+      MINIO_ROOT_USER: minio_root
+      MINIO_ROOT_PASSWORD: m1n1opwd
+    command:
+      - "server"
+      - "/data"
+      - "--console-address"
+      - ":9001"
+    healthcheck:
+      test: ["CMD", "curl", "http://127.0.0.1:9000/minio/health/live"]
+      interval: 1s
+      timeout: 10s
+
+  polaris:
+    image: apache/polaris:latest
+    ports:
+      # API port
+      - "8181:8181"
+      # Management port (metrics and health checks)
+      - "8182:8182"
+      # Optional, allows attaching a debugger to the Polaris JVM
+      - "5005:5005"
+    depends_on:
+      minio:
+        condition: service_healthy
+    environment:
+      JAVA_DEBUG: true
+      JAVA_DEBUG_PORT: "*:5005"
+      AWS_REGION: us-west-2
+      AWS_ACCESS_KEY_ID: minio_root
+      AWS_SECRET_ACCESS_KEY: m1n1opwd
+      POLARIS_BOOTSTRAP_CREDENTIALS: POLARIS,${ROOT_CLIENT_ID:-root},${ROOT_CLIENT_SECRET:-s3cr3t}
+      polaris.realm-context.realms: ${POLARIS_REALM:-POLARIS}
+      quarkus.otel.sdk.disabled: "true"
+    healthcheck:
+      test: ["CMD", "curl", "http://localhost:8182/q/health"]
+      interval: 2s
+      timeout: 10s
+      retries: 10
+      start_period: 10s
+
+  setup_bucket:
+    image: quay.io/minio/mc:latest
+    depends_on:
+      minio:
+        condition: service_healthy
+    entrypoint: "/bin/sh"
+    command:
+      - "-c"
+      - >-
+        echo Creating MinIO bucket...;
+        mc alias set pol http://minio:9000 minio_root m1n1opwd;
+        mc mb pol/bucket123;
+        mc ls pol;
+        echo Bucket setup complete.;
+
+  polaris-setup:
+    image: alpine/curl
+    depends_on:
+      polaris:
+        condition: service_healthy
+    environment:
+      - CLIENT_ID=${ROOT_CLIENT_ID:-root}
+      - CLIENT_SECRET=${ROOT_CLIENT_SECRET:-s3cr3t}
+      - CATALOG_NAME=${CATALOG_NAME:-quickstart_catalog}
+      - REALM=${POLARIS_REALM:-POLARIS}
+    entrypoint: /bin/sh
+    command:
+      - -c
+      - |
+        set -e
+        apk add --no-cache jq
+
+        echo "Obtaining root access token..."
+        TOKEN_RESPONSE=$$(curl -s -X POST http://polaris:8181/api/catalog/v1/oauth/tokens \
+          -H 'Content-Type: application/x-www-form-urlencoded' \
+          -d "grant_type=client_credentials&client_id=$${CLIENT_ID}&client_secret=$${CLIENT_SECRET}&scope=PRINCIPAL_ROLE:ALL")
+
+        TOKEN=$$(echo $$TOKEN_RESPONSE | jq -r '.access_token')
+        echo "Obtained access token"
+
+        echo "Creating catalog '$$CATALOG_NAME' in realm $$REALM..."
+        PAYLOAD='{
+          "catalog": {
+            "name": "'$$CATALOG_NAME'",
+            "type": "INTERNAL",
+            "readOnly": false,
+            "properties": {
+              "default-base-location": "s3://bucket123"
+            },
+            "storageConfigInfo": {
+              "storageType": "S3",
+              "allowedLocations": ["s3://bucket123"],
+              "endpoint": "http://localhost:9000",
+              "endpointInternal": "http://minio:9000",
+              "pathStyleAccess": true
+            }
+          }
+        }'
+
+        curl -s -X POST http://polaris:8181/api/management/v1/catalogs \
+          -H "Authorization: Bearer $$TOKEN" \
+          -H "Accept: application/json" \
+          -H "Content-Type: application/json" \
+          -H "Polaris-Realm: $$REALM" \
+          -d "$$PAYLOAD" > /dev/null
+
+        echo "✅ Catalog created"
+
+        echo ""
+        echo "Creating principal 'quickstart_user'..."
+        PRINCIPAL_RESPONSE=$$(curl -s -X POST http://polaris:8181/api/management/v1/principals \
+          -H "Authorization: Bearer $$TOKEN" \
+          -H "Polaris-Realm: $$REALM" \
+          -H "Content-Type: application/json" \
+          -d '{"principal": {"name": "quickstart_user", "properties": {}}}')
+
+        USER_CLIENT_ID=$$(echo $$PRINCIPAL_RESPONSE | jq -r '.credentials.clientId')
+        USER_CLIENT_SECRET=$$(echo $$PRINCIPAL_RESPONSE | jq -r '.credentials.clientSecret')
+
+        echo "✅ Principal created with clientId: $$USER_CLIENT_ID"
+
+        echo "Creating principal role 'quickstart_user_role'..."
+        curl -s -X POST http://polaris:8181/api/management/v1/principal-roles \
+          -H "Authorization: Bearer $$TOKEN" \
+          -H "Polaris-Realm: $$REALM" \
+          -H "Content-Type: application/json" \
+          -d '{"principalRole": {"name": "quickstart_user_role", "properties": {}}}' > /dev/null
+
+        echo "✅ Principal role created"
+
+        echo "Creating catalog role 'quickstart_catalog_role'..."
+        curl -s -X POST http://polaris:8181/api/management/v1/catalogs/$$CATALOG_NAME/catalog-roles \
+          -H "Authorization: Bearer $$TOKEN" \
+          -H "Polaris-Realm: $$REALM" \
+          -H "Content-Type: application/json" \
+          -d '{"catalogRole": {"name": "quickstart_catalog_role", "properties": {}}}' > /dev/null
+
+        echo "✅ Catalog role created"
+
+        echo "Assigning principal role to principal..."
+        curl -s -X PUT http://polaris:8181/api/management/v1/principals/quickstart_user/principal-roles \
+          -H "Authorization: Bearer $$TOKEN" \
+          -H "Polaris-Realm: $$REALM" \
+          -H "Content-Type: application/json" \
+          -d '{"principalRole": {"name": "quickstart_user_role"}}' > /dev/null
+
+        echo "✅ Principal role assigned"
+
+        echo "Assigning catalog role to principal role..."
+        curl -s -X PUT http://polaris:8181/api/management/v1/principal-roles/quickstart_user_role/catalog-roles/$$CATALOG_NAME \
+          -H "Authorization: Bearer $$TOKEN" \
+          -H "Polaris-Realm: $$REALM" \
+          -H "Content-Type: application/json" \
+          -d '{"catalogRole": {"name": "quickstart_catalog_role"}}' > /dev/null
+
+        echo "✅ Catalog role assigned"
+
+        echo "Granting CATALOG_MANAGE_CONTENT privilege..."
+        curl -s -X PUT http://polaris:8181/api/management/v1/catalogs/$$CATALOG_NAME/catalog-roles/quickstart_catalog_role/grants \
+          -H "Authorization: Bearer $$TOKEN" \
+          -H "Polaris-Realm: $$REALM" \
+          -H "Content-Type: application/json" \
+          -d '{"type": "catalog", "privilege": "CATALOG_MANAGE_CONTENT"}' > /dev/null
+
+        echo "✅ Privileges granted"
+
+        echo ""
+        echo "=========================================="
+        echo "🎉 Polaris Quickstart Setup Complete!"
+        echo "=========================================="
+        echo ""
+        echo "Catalog: $$CATALOG_NAME"
+        echo "  Storage: S3 (MinIO)"
+        echo "  Location: s3://bucket123"
+        echo "  MinIO UI: http://localhost:9001"
+        echo ""
+        echo "Root credentials:"
+        echo "  Client ID:     $$CLIENT_ID"
+        echo "  Client Secret: $$CLIENT_SECRET"
+        echo ""
+        echo "User credentials:"
+        echo "  Client ID:     $$USER_CLIENT_ID"
+        echo "  Client Secret: $$USER_CLIENT_SECRET"
+        echo ""
+        echo "Polaris main APIs:"
+        echo "  - Iceberg REST:   http://localhost:8181/api/catalog/v1"
+        echo "  - Management:     http://localhost:8181/api/management/v1"
+        echo "  - Generic Tables: http://localhost:8181/api/polaris/v1"
+        echo ""
+        echo "Polaris admin APIs:"
+        echo "  - Health check:   http://localhost:8182/q/health"
+        echo "  - Metrics:        http://localhost:8182/q/metrics"
+        echo ""
+        echo "To get started with Spark:"
+        echo "  spark-sql \\"
+        echo "    --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.10.0,org.apache.iceberg:iceberg-aws-bundle:1.10.0 \\"
+        echo "    --conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions \\"
+        echo "    --conf spark.sql.catalog.polaris=org.apache.iceberg.spark.SparkCatalog \\"
+        echo "    --conf spark.sql.catalog.polaris.type=rest \\"
+        echo "    --conf spark.sql.catalog.polaris.warehouse=$$CATALOG_NAME \\"
+        echo "    --conf spark.sql.catalog.polaris.uri=http://localhost:8181/api/catalog \\"
+        echo "    --conf spark.sql.catalog.polaris.credential=$$USER_CLIENT_ID:$$USER_CLIENT_SECRET \\"
+        echo "    --conf spark.sql.catalog.polaris.scope=PRINCIPAL_ROLE:ALL \\"
+        echo "    --conf spark.sql.catalog.polaris.s3.endpoint=http://localhost:9000 \\"
+        echo "    --conf spark.sql.catalog.polaris.s3.path-style-access=true \\"
+        echo "    --conf spark.sql.catalog.polaris.s3.access-key-id=minio_root \\"
+        echo "    --conf spark.sql.catalog.polaris.s3.secret-access-key=m1n1opwd \\"
+        echo "    --conf spark.sql.catalog.polaris.client.region=irrelevant \\"
+        echo "    --conf spark.sql.defaultCatalog=polaris"
+        echo ""
+        echo "To get started with REST API:"
+        echo "  # Get a token"
+        echo "  export TOKEN=\$$(curl -s -X POST http://localhost:8181/api/catalog/v1/oauth/tokens \\"
+        echo "    -d 'grant_type=client_credentials' \\"
+        echo "    -d 'client_id=$$USER_CLIENT_ID' \\"
+        echo "    -d 'client_secret=$$USER_CLIENT_SECRET' \\"
+        echo "    -d 'scope=PRINCIPAL_ROLE:ALL' \\"
+        echo "    | jq -r '.access_token')"
+        echo ""
+        echo "  # Create a namespace"
+        echo "  curl -X POST http://localhost:8181/api/catalog/v1/$$CATALOG_NAME/namespaces \\"
+        echo "    -H \"Authorization: Bearer \$$TOKEN\" \\"
+        echo "    -H 'Content-Type: application/json' \\"
+        echo "    -d '{\"namespace\": [\"my_namespace\"], \"properties\": {}}'"
+        echo ""
+        echo "  # List namespaces"
+        echo "  curl -X GET http://localhost:8181/api/catalog/v1/$$CATALOG_NAME/namespaces \\"
+        echo "    -H \"Authorization: Bearer \$$TOKEN\""
+        echo ""
+        echo "=========================================="
diff --git a/site/content/in-dev/unreleased/getting-started/_index.md b/site/content/in-dev/unreleased/getting-started/_index.md
@@ -23,16 +23,21 @@ type: docs
 weight: 101
 ---
 
-The fastest way to get started is with our Docker Compose examples. Each example provides a complete working environment with detailed instructions.
+There are several options for getting started with Apache Polaris.
 
-## Next Steps
+To quickly try out Apache Polaris, please use the [quickstart guide](./quick-start). For other examples, please see below.
 
-1. Check/Install dependencies
+## Docker Compose Examples
+Each of the proceeding Docker Compose examples provides a complete working environment with detailed instructions.
+
+### Next Steps
+
+1. Check & install dependencies
 2. Choose the way you want to deploy Polaris
 3. Create a catalog
-4. Check Using polaris page
+4. Check Using Polaris page
 
-## Getting Help
+### Getting Help
 
 - Documentation: https://polaris.apache.org
 - GitHub Issues: https://github.com/apache/polaris/issues
diff --git a/site/content/in-dev/unreleased/getting-started/quick-start.md b/site/content/in-dev/unreleased/getting-started/quick-start.md
@@ -0,0 +1,42 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+Title: Quickstart
+type: docs
+weight: 99
+---
+Use this guide to quickly start running Polaris. This is not intended for production use.
+
+## Prerequisites
+
+- Have Docker (with Docker Compose v2) installed & running on your machine
+
+## Running
+
+Run the following command:
+
+```bash
+curl -s https://raw.githubusercontent.com/apache/polaris/main/getting-started/quickstart/docker-compose.yml | docker compose -f - up
+
+```
+This command will:
+1. Create a Catalog named `quickstart_catalog` with MinIO-backed storage.
+2. Create a user principal `quickstart_user` with full access to the catalog.
+
+Once the command has been run, you will see examples on how to interact with this Polaris server in the logs.
