Revamp the Quick Start page

getting-started/README.md

@@ -33,12 +33,10 @@ this directory. Each example has detailed instructions.
 - [Spark](spark): An example that uses an in-memory metastore, automatically bootstrapped, with
   Apache Spark and a Jupyter notebook.
 
-- [Trino](trino): An example that uses Trino with Polaris.
-
 - [Telemetry](telemetry): An example that includes Prometheus and Jaeger to collect metrics and
   traces from Apache Polaris. This example automatically creates a `polaris_demo` catalog.
 
 - [Eclipselink](eclipselink): An example that uses an Eclipselink metastore and a Postgres
   database. The realm is bootstrapped with the Polaris Admin tool. This example also creates a
-  `polaris_demo` catalog, and offers the ability to run Spark SQL queries. Finally, it shows how to
+  `polaris_quickstart` catalog, and offers the ability to run Spark SQL and Trino queries. Finally, it shows how to
   attach a debugger to the Polaris server.

getting-started/assets/cloud_providers/deploy-aws.sh

@@ -0,0 +1,78 @@
+#
+# 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.
+#
+
+EC2_INSTANCE_ID=$(cat /var/lib/cloud/data/instance-id)
+
+DESCRIBE_INSTANCE=$(aws ec2 describe-instances \
+    --instance-ids $EC2_INSTANCE_ID \
+    --query 'Reservations[*].Instances[*].{Instance:InstanceId,VPC:VpcId,AZ:Placement.AvailabilityZone}' \
+    --output json)
+
+CURRENT_VPC=$(echo $DESCRIBE_INSTANCE | jq -r .[0].[0]."VPC")
+
+CURRENT_REGION=$(echo $DESCRIBE_INSTANCE | jq -r .[0].[0]."AZ" | sed 's/.$//')
+
+ALL_SUBNETS=$(aws ec2 describe-subnets \
+  --region $CURRENT_REGION \
+  --query 'Subnets[*].{SubnetId:SubnetId}' \
+  --output json \
+  | jq -r '[.[]["SubnetId"]] | join(" ")')
+
+RANDOM_SUFFIX=$(head /dev/urandom | tr -dc 'A-Za-z0-9' | head -c 8)
+SUBNET_GROUP_NAME="polaris-db-subnet-group-$RANDOM_SUFFIX"
+INSTANCE_NAME="polaris-backend-test-$RANDOM_SUFFIX"
+
+aws rds create-db-subnet-group \
+  --db-subnet-group-name $SUBNET_GROUP_NAME \
+  --db-subnet-group-description "Apache Polaris Quickstart DB Subnet Group" \
+  --subnet-ids $ALL_SUBNETS
+
+DB_INSTANCE_INFO=$(aws rds create-db-instance \
+  --db-instance-identifier $INSTANCE_NAME \
+  --db-instance-class db.t3.micro \
+  --engine postgres \
+  --master-username postgres \
+  --master-user-password postgres \
+  --db-name POLARIS \
+  --db-subnet-group-name $SUBNET_GROUP_NAME \
+  --allocated-storage 10)
+
+DB_ARN=$(echo $DB_INSTANCE_INFO | jq -r '.["DBInstance"]["DBInstanceArn"]')
+
+DESCRIBE_DB=$(aws rds describe-db-instances --db-instance-identifier $DB_ARN)
+
+until echo $DESCRIBE_DB | jq -e '.["DBInstances"][0] | has("Endpoint")';
+do
+  echo "sleeping 10s to wait for Postgres DB provisioning..."
+  sleep 10
+  DESCRIBE_DB=$(aws rds describe-db-instances --db-instance-identifier $DB_ARN)
+done
+
+POSTGRES_ADDR=$(echo $DESCRIBE_DB | jq -r '.["DBInstances"][0]["Endpoint"]' | jq -r '"\(.Address):\(.Port)"')
+
+FULL_POSTGRES_ADDR=$(printf '%s\n' "jdbc:postgresql://$POSTGRES_ADDR/{realm}" | sed 's/[&/\]/\\&/g')
+sed -i "/jakarta.persistence.jdbc.url/ s|value=\"[^\"]*\"|value=\"$FULL_POSTGRES_ADDR\"|" "getting-started/assets/eclipselink/persistence.xml"
+
+./gradlew clean :polaris-quarkus-server:assemble :polaris-quarkus-admin:assemble \
+       -PeclipseLinkDeps=org.postgresql:postgresql:42.7.4 \
+       -Dquarkus.container-image.tag=postgres-latest \
+       -Dquarkus.container-image.build=true \
+       --no-build-cache
+
+docker compose -f getting-started/eclipselink/docker-compose-bootstrap-db.yml -f getting-started/eclipselink/docker-compose.yml up -d

getting-started/assets/cloud_providers/deploy-azure.sh

@@ -0,0 +1,40 @@
+#
+# 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.
+#
+
+CURRENT_REGION=$(curl -H Metadata:true "http://169.254.169.254/metadata/instance?api-version=2021-02-01" | jq -r '.compute.location')
+CURRENT_RESOURCE_GROUP=$(curl -H Metadata:true "http://169.254.169.254/metadata/instance?api-version=2021-02-01" | jq -r '.compute.resourceGroupName')
+RANDOM_SUFFIX=$(head /dev/urandom | tr -dc 'a-z0-9' | head -c 8)
+INSTANCE_NAME="polaris-backend-test-$RANDOM_SUFFIX"
+
+CREATE_DB_RESPONSE=$(az postgres flexible-server create -l $CURRENT_REGION -g $CURRENT_RESOURCE_GROUP -n $INSTANCE_NAME -u postgres -p postgres -y)
+
+az postgres flexible-server db create -g $CURRENT_RESOURCE_GROUP -s $INSTANCE_NAME -d POLARIS
+
+POSTGRES_ADDR=$(echo $CREATE_DB_RESPONSE | jq -r '.host')
+
+FULL_POSTGRES_ADDR=$(printf '%s\n' "jdbc:postgresql://$POSTGRES_ADDR:5432/{realm}" | sed 's/[&/\]/\\&/g')
+sed -i "/jakarta.persistence.jdbc.url/ s|value=\"[^\"]*\"|value=\"$FULL_POSTGRES_ADDR\"|" "getting-started/assets/eclipselink/persistence.xml"
+
+./gradlew clean :polaris-quarkus-server:assemble :polaris-quarkus-admin:assemble \
+       -PeclipseLinkDeps=org.postgresql:postgresql:42.7.4 \
+       -Dquarkus.container-image.tag=postgres-latest \
+       -Dquarkus.container-image.build=true \
+       --no-build-cache
+
+docker compose -f getting-started/eclipselink/docker-compose-bootstrap-db.yml -f getting-started/eclipselink/docker-compose.yml up -d

getting-started/assets/cloud_providers/deploy-gcp.sh

@@ -0,0 +1,50 @@
+#
+# 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.
+#
+
+CURRENT_ZONE=$(curl -H "Metadata-Flavor: Google" "http://169.254.169.254/computeMetadata/v1/instance/zone" | awk -F/ '{print $NF}')
+CURRENT_REGION=$(echo $CURRENT_ZONE | sed 's/-[a-z]$//')
+VM_INSTANCE_NAME=$(curl -H "Metadata-Flavor: Google" "http://169.254.169.254/computeMetadata/v1/instance/name")
+RANDOM_SUFFIX=$(head /dev/urandom | tr -dc 'a-z0-9' | head -c 8)
+DB_INSTANCE_NAME="polaris-backend-test-$RANDOM_SUFFIX"
+
+INSTANCE_IP=$(gcloud compute instances describe $VM_INSTANCE_NAME --zone=$CURRENT_ZONE --format="get(networkInterfaces[0].accessConfigs[0].natIP)")
+
+
+gcloud sql instances create $DB_INSTANCE_NAME \
+  --database-version=POSTGRES_17 \
+  --region=$CURRENT_REGION \
+  --tier=db-perf-optimized-N-4 \
+  --edition=ENTERPRISE_PLUS \
+  --root-password=postgres \
+  --authorized-networks="$INSTANCE_IP/32"
+
+gcloud sql databases create POLARIS --instance=$DB_INSTANCE_NAME
+
+POSTGRES_ADDR=$(gcloud sql instances describe $DB_INSTANCE_NAME --format="get(ipAddresses[0].ipAddress)")
+
+FULL_POSTGRES_ADDR=$(printf '%s\n' "jdbc:postgresql://$POSTGRES_ADDR:5432/{realm}" | sed 's/[&/\]/\\&/g')
+sed -i "/jakarta.persistence.jdbc.url/ s|value=\"[^\"]*\"|value=\"$FULL_POSTGRES_ADDR\"|" "getting-started/assets/eclipselink/persistence.xml"
+
+./gradlew clean :polaris-quarkus-server:assemble :polaris-quarkus-admin:assemble \
+       -PeclipseLinkDeps=org.postgresql:postgresql:42.7.4 \
+       -Dquarkus.container-image.tag=postgres-latest \
+       -Dquarkus.container-image.build=true \
+       --no-build-cache
+
+docker compose -f getting-started/eclipselink/docker-compose-bootstrap-db.yml -f getting-started/eclipselink/docker-compose.yml up -d

getting-started/assets/eclipselink/persistence.xml

@@ -32,8 +32,7 @@
     <class>org.apache.polaris.jpa.models.ModelSequenceId</class>
     <shared-cache-mode>NONE</shared-cache-mode>
     <properties>
-      <property name="jakarta.persistence.jdbc.url"
-        value="jdbc:postgresql://postgres:5432/{realm}"/>
+      <property name="jakarta.persistence.jdbc.url" value="jdbc:postgresql://postgres:5432/{realm}"/>
       <property name="jakarta.persistence.jdbc.user" value="postgres"/>
       <property name="jakarta.persistence.jdbc.password" value="postgres"/>
       <property name="jakarta.persistence.schema-generation.database.action" value="create"/>

getting-started/assets/polaris/create-catalog.sh

@@ -33,24 +33,24 @@ echo
 echo "Obtained access token: ${token}"
 
 echo
-echo Creating a catalog named polaris_demo...
+echo Creating a catalog named quickstart_catalog...
 
 curl -s -H "Authorization: Bearer ${token}" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    http://polaris:8181/api/management/v1/catalogs \
    -d '{
      "catalog": {
-       "name": "polaris_demo",
+       "name": "quickstart_catalog",
        "type": "INTERNAL",
        "readOnly": false,
        "properties": {
-         "default-base-location": "file:///tmp/polaris/"
+         "default-base-location": "file:///var/tmp/quickstart_catalog/"
        },
        "storageConfigInfo": {
          "storageType": "FILE",
          "allowedLocations": [
-           "file:///tmp"
+           "file:///var/tmp"
          ]
        }
      }

getting-started/eclipselink/README.md

@@ -38,7 +38,7 @@ This example requires `jq` to be installed on your machine.
 2. Start the docker compose group by running the following command from the root of the repository:
 
     ```shell
-    docker compose -f getting-started/eclipselink/docker-compose.yml up
+    docker compose -f getting-started/eclipselink/docker-compose-postgres.yml -f getting-started/eclipselink/docker-compose-bootstrap-db.yml -f getting-started/eclipselink/docker-compose.yml up
     ```
 
 3. Using spark-sql: attach to the running spark-sql container:
@@ -71,5 +71,23 @@ This example requires `jq` to be installed on your machine.
 
     ```shell
     curl -v http://127.0.0.1:8181/api/management/v1/principal-roles -H "Authorization: Bearer $POLARIS_TOKEN"
-    curl -v http://127.0.0.1:8181/api/catalog/v1/config?warehouse=polaris_demo -H "Authorization: Bearer $POLARIS_TOKEN"
+    curl -v http://127.0.0.1:8181/api/management/v1/catalogs/polaris_demo -H "Authorization: Bearer $POLARIS_TOKEN"
     ```
+
+6. Using Trino CLI: To access the Trino CLI, run this command:
+```
+docker exec -it eclipselink-trino-1 trino
+```
+Note, `trino-trino-1` is the name of the Docker container.
+
+Example Trino queries:
+```
+SHOW CATALOGS;
+SHOW SCHEMAS FROM iceberg;
+SHOW TABLES FROM iceberg.information_schema;
+DESCRIBE iceberg.information_schema.tables;
+
+CREATE SCHEMA iceberg.tpch;
+CREATE TABLE iceberg.tpch.test_polaris AS SELECT 1 x;
+SELECT * FROM iceberg.tpch.test_polaris;
+```

getting-started/eclipselink/docker-compose-bootstrap-db.yml

@@ -0,0 +1,32 @@
+#
+# 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:
+  polaris-bootstrap:
+    # IMPORTANT: the image MUST contain the Postgres JDBC driver and EclipseLink dependencies, see README for instructions
+    image: apache/polaris-admin-tool:postgres-latest
+    environment:
+      polaris.persistence.type: eclipse-link
+      polaris.persistence.eclipselink.configuration-file: /deployments/config/eclipselink/persistence.xml
+    volumes:
+      - ../assets/eclipselink/:/deployments/config/eclipselink
+    command:
+      - "bootstrap"
+      - "--realm=POLARIS"
+      - "--credential=POLARIS,root,s3cr3t"

getting-started/eclipselink/docker-compose-postgres.yml

@@ -0,0 +1,45 @@
+#
+# 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:
+  postgres:
+    image: postgres:17.4
+    ports:
+      - "5432:5432"
+    # set shared memory limit when using docker-compose
+    shm_size: 128mb
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: POLARIS
+      POSTGRES_INITDB_ARGS: "--encoding UTF8 --data-checksums"
+    volumes:
+      # Bind local conf file to a convenient location in the container
+      - type: bind
+        source: ./postgresql.conf
+        target: /etc/postgresql/postgresql.conf
+    command:
+      - "postgres"
+      - "-c"
+      - "config_file=/etc/postgresql/postgresql.conf"
+    healthcheck:
+      test: "pg_isready -U postgres"
+      interval: 5s
+      timeout: 2s
+      retries: 15