Fix quickstart doc with docker compose (#1610)

MonkeyCanCode · web-flow · commit 0eafcaa4678d · 2025-05-22T22:43:33.000-07:00
diff --git a/getting-started/assets/postgres/docker-compose-postgres.yml b/getting-started/assets/postgres/docker-compose-postgres.yml
@@ -32,7 +32,7 @@ services:
     volumes:
       # Bind local conf file to a convenient location in the container
       - type: bind
-        source: ../assets/postgres/postgresql.conf
+        source: ${ASSETS_PATH}/postgres/postgresql.conf
         target: /etc/postgresql/postgresql.conf
     command:
       - "postgres"
diff --git a/getting-started/eclipselink/README.md b/getting-started/eclipselink/README.md
@@ -37,7 +37,12 @@ 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-bootstrap-db.yml -f getting-started/assets/postgres/docker-compose-postgres.yml -f getting-started/eclipselink/docker-compose.yml up
+    export ASSETS_PATH=$(pwd)/getting-started/assets/
+    export CLIENT_ID=root
+    export CLIENT_SECRET=s3cr3t
+    docker compose -p polaris -f getting-started/assets/postgres/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:
diff --git a/getting-started/eclipselink/docker-compose-bootstrap-db.yml b/getting-started/eclipselink/docker-compose-bootstrap-db.yml
@@ -25,11 +25,11 @@ services:
       polaris.persistence.type: eclipse-link
       polaris.persistence.eclipselink.configuration-file: /deployments/config/eclipselink/persistence.xml
     volumes:
-      - ../assets/eclipselink/:/deployments/config/eclipselink
+      - ${ASSETS_PATH}/eclipselink/:/deployments/config/eclipselink
     command:
       - "bootstrap"
       - "--realm=POLARIS"
-      - "--credential=POLARIS,root,s3cr3t"
+      - "--credential=POLARIS,${CLIENT_ID},${CLIENT_SECRET}"
   polaris:
     depends_on:
       polaris-bootstrap:
diff --git a/getting-started/eclipselink/docker-compose.yml b/getting-started/eclipselink/docker-compose.yml
@@ -41,7 +41,7 @@ services:
       polaris.features."SUPPORTED_CATALOG_STORAGE_TYPES": "[\"FILE\",\"S3\",\"GCS\",\"AZURE\"]"
       polaris.readiness.ignore-severe-issues: "true"
     volumes:
-      - ../assets/eclipselink/:/deployments/config/eclipselink
+      - ${ASSETS_PATH}/eclipselink/:/deployments/config/eclipselink
     healthcheck:
       test: ["CMD", "curl", "http://localhost:8182/q/health"]
       interval: 2s
@@ -61,7 +61,7 @@ services:
       - CLIENT_ID=${CLIENT_ID}
       - CLIENT_SECRET=${CLIENT_SECRET}
     volumes:
-      - ../assets/polaris/:/polaris
+      - ${ASSETS_PATH}/polaris/:/polaris
     entrypoint: '/bin/sh -c "chmod +x /polaris/create-catalog.sh && /polaris/create-catalog.sh"'
 
   spark-sql:
@@ -98,11 +98,11 @@ services:
       polaris-setup:
         condition: service_completed_successfully
     environment:
-      - CLIENT_ID=${CLIENT_ID}
-      - CLIENT_SECRET=${CLIENT_SECRET}
+      - CLIENT_ID=${USER_CLIENT_ID}
+      - CLIENT_SECRET=${USER_CLIENT_SECRET}
     stdin_open: true
     tty: true
     ports:
       - "8080:8080"
     volumes:
-      - ../assets/trino-config/catalog:/etc/trino/catalog
+      - ${ASSETS_PATH}/trino-config/catalog:/etc/trino/catalog
diff --git a/getting-started/jdbc/README.md b/getting-started/jdbc/README.md
@@ -40,6 +40,7 @@ This example requires `jq` to be installed on your machine.
     export QUARKUS_DATASOURCE_JDBC_URL=jdbc:postgresql://postgres:5432/POLARIS
     export QUARKUS_DATASOURCE_USERNAME=postgres
     export QUARKUS_DATASOURCE_PASSWORD=postgres
+    export ASSETS_PATH=$(pwd)/getting-started/assets/
     export CLIENT_ID=root
     export CLIENT_SECRET=s3cr3t
     docker compose -f getting-started/jdbc/docker-compose-bootstrap-db.yml -f getting-started/assets/postgres/docker-compose-postgres.yml -f getting-started/jdbc/docker-compose.yml up
diff --git a/getting-started/jdbc/docker-compose.yml b/getting-started/jdbc/docker-compose.yml
@@ -64,7 +64,7 @@ services:
       - CLIENT_ID=${CLIENT_ID}
       - CLIENT_SECRET=${CLIENT_SECRET}
     volumes:
-      - ../assets/polaris/:/polaris
+      - ${ASSETS_PATH}/polaris/:/polaris
     entrypoint: '/bin/sh -c "chmod +x /polaris/create-catalog.sh && /polaris/create-catalog.sh"'
 
   spark-sql:
@@ -108,4 +108,4 @@ services:
       - CLIENT_ID=${CLIENT_ID}
       - CLIENT_SECRET=${CLIENT_SECRET}
     volumes:
-      - ../assets/trino-config/catalog:/etc/trino/catalog
+      - ${ASSETS_PATH}/trino-config/catalog:/etc/trino/catalog
diff --git a/site/content/in-dev/unreleased/getting-started/deploying-polaris/quickstart-deploy-aws.md b/site/content/in-dev/unreleased/getting-started/deploying-polaris/quickstart-deploy-aws.md
@@ -37,6 +37,7 @@ The requirements to run the script below are:
 
 ```shell
 chmod +x getting-started/assets/cloud_providers/deploy-aws.sh
+export ASSETS_PATH=$(pwd)/getting-started/assets/
 ./getting-started/assets/cloud_providers/deploy-aws.sh
 ```
 
@@ -50,6 +51,7 @@ export CLIENT_SECRET=s3cr3t
 To shut down the Polaris server, run the following commands:
 
 ```shell
+export ASSETS_PATH=$(pwd)/getting-started/assets/
 docker compose -f getting-started/eclipselink/docker-compose.yml down
 ```
 
diff --git a/site/content/in-dev/unreleased/getting-started/deploying-polaris/quickstart-deploy-azure.md b/site/content/in-dev/unreleased/getting-started/deploying-polaris/quickstart-deploy-azure.md
@@ -32,6 +32,7 @@ The requirements to run the script below are:
 
 ```shell
 chmod +x getting-started/assets/cloud_providers/deploy-azure.sh
+export ASSETS_PATH=$(pwd)/getting-started/assets/
 ./getting-started/assets/cloud_providers/deploy-azure.sh
 ```
 
@@ -45,6 +46,7 @@ export CLIENT_SECRET=s3cr3t
 To shut down the Polaris server, run the following commands:
 
 ```shell
+export ASSETS_PATH=$(pwd)/getting-started/assets/
 docker compose -f getting-started/eclipselink/docker-compose.yml down
 ```
 
diff --git a/site/content/in-dev/unreleased/getting-started/deploying-polaris/quickstart-deploy-gcp.md b/site/content/in-dev/unreleased/getting-started/deploying-polaris/quickstart-deploy-gcp.md
@@ -32,6 +32,7 @@ The requirements to run the script below are:
 
 ```shell
 chmod +x getting-started/assets/cloud_providers/deploy-gcp.sh
+export ASSETS_PATH=$(pwd)/getting-started/assets/
 ./getting-started/assets/cloud_providers/deploy-gcp.sh
 ```
 
@@ -45,6 +46,7 @@ export CLIENT_SECRET=s3cr3t
 To shut down the Polaris server, run the following commands:
 
 ```shell
+export ASSETS_PATH=$(pwd)/getting-started/assets/
 docker compose -f getting-started/eclipselink/docker-compose.yml down
 ```
 
diff --git a/site/content/in-dev/unreleased/getting-started/quickstart.md b/site/content/in-dev/unreleased/getting-started/quickstart.md
@@ -24,10 +24,10 @@ weight: 200
 
 Polaris can be deployed via a docker image or as a standalone process. Before starting, be sure that you've satisfied the relevant prerequisites detailed in the previous page.
 
-## Docker Image
-
-To start using Polaris in Docker, build and launch Polaris, which is packaged with a Postgres instance, Apache Spark, and Trino. 
+## Common Setup
+Before running Polaris, ensure you have completed the following setup steps:
 
+1. **Build Polaris**
 ```shell
 cd ~/polaris
 ./gradlew \
@@ -36,7 +36,20 @@ cd ~/polaris
   :polaris-quarkus-admin:assemble --rerun \
   -Dquarkus.container-image.tag=postgres-latest \
   -Dquarkus.container-image.build=true
-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
+```
+- **For standalone**: Omit the `-Dquarkus.container-image.tag` and `-Dquarkus.container-image.build` options if you do not need to build a Docker image.
+
+## Running Polaris with Docker
+
+To start using Polaris in Docker and launch Polaris, which is packaged with a Postgres instance, Apache Spark, and Trino. 
+
+```shell
+export ASSETS_PATH=$(pwd)/getting-started/assets/
+export CLIENT_ID=root
+export CLIENT_SECRET=s3cr3t
+docker compose -p polaris -f getting-started/assets/postgres/docker-compose-postgres.yml \
+  -f getting-started/eclipselink/docker-compose-bootstrap-db.yml \
+  -f getting-started/eclipselink/docker-compose.yml up
 ```
 
 You should see output for some time as Polaris, Spark, and Trino build and start up. Eventually, you won’t see any more logs and see some logs relating to Spark, resembling the following:
@@ -48,24 +61,17 @@ spark-sql-1          | 25/04/04 05:39:38 WARN SparkSQLCLIDriver: WARNING: Direct
 spark-sql-1          | 25/04/04 05:39:39 WARN RESTSessionCatalog: Iceberg REST client is missing the OAuth2 server URI configuration and defaults to http://polaris:8181/api/catalogv1/oauth/tokens. This automatic fallback will be removed in a future Iceberg release.It is recommended to configure the OAuth2 endpoint using the 'oauth2-server-uri' property to be prepared. This warning will disappear if the OAuth2 endpoint is explicitly configured. See https://github.com/apache/iceberg/issues/10537
 ```
 
-Finally, set the following static credentials for interacting with the Polaris server in the following exercises:
-
-```shell
-export CLIENT_ID=root
-export CLIENT_SECRET=s3cr3t
-```
-
 The Docker image pre-configures a sample catalog called `quickstart_catalog` that uses a local file system.
 
 ## Running Polaris as a Standalone Process
 
 You can also start Polaris through Gradle (packaged within the Polaris repository):
 
+1. **Start the Server**  
+
+Run the following command to start Polaris:
+
 ```shell
-cd ~/polaris
-# Build the server
-./gradlew clean :polaris-quarkus-server:assemble :polaris-quarkus-server:quarkusAppPartsBuild --rerun
-# Start the server
 ./gradlew run
 ```
 
@@ -83,11 +89,6 @@ When using a Gradle-launched Polaris instance in this tutorial, we'll launch an
 For more information on how to configure Polaris for production usage, see the [docs]({{% relref "../configuring-polaris-for-production" %}}).
 
 When Polaris is run using the `./gradlew run` command, the root principal credentials are `root` and `secret` for the `CLIENT_ID` and `CLIENT_SECRET`, respectively.
-You can also set these credentials as environment variables for use with the Polaris CLI:
-```shell
-export CLIENT_ID=root
-export CLIENT_SECRET=secret
-```
 
 ### Installing Apache Spark and Trino Locally for Testing
 
diff --git a/site/content/in-dev/unreleased/getting-started/using-polaris.md b/site/content/in-dev/unreleased/getting-started/using-polaris.md
@@ -21,12 +21,16 @@ Title: Using Polaris
 type: docs
 weight: 400
 ---
+
 ## Setup
+
 Define your `CLIENT_ID` & `CLIENT_SECRET` and export them for future use.
+
 ```shell
 export CLIENT_ID=YOUR_CLIENT_ID
 export CLIENT_SECRET=YOUR_CLIENT_SECRET
 ```
+
 ## Defining a Catalog
 
 In Polaris, the [catalog]({{% relref "../entities#catalog" %}}) is the top-level entity that objects like [tables]({{% relref "../entities#table" %}}) and [views]({{% relref "../entities#view" %}}) are organized under. With a Polaris service running, you can create a catalog like so:
@@ -167,7 +171,6 @@ bin/spark-sql \
 --conf spark.sql.catalog.quickstart_catalog.client.region=us-west-2
 ```
 
-
 Similar to the CLI commands above, this configures Spark to use the Polaris running at `localhost:8181`. If your Polaris server is running elsewhere, but sure to update the configuration appropriately.
 
 Finally, note that we include the `iceberg-aws-bundle` package here. If your table is using a different filesystem, be sure to include the appropriate dependency.
@@ -176,7 +179,9 @@ Finally, note that we include the `iceberg-aws-bundle` package here. If your tab
 
 Refresh the Docker container with the user's credentials:
 ```shell
-docker compose -f getting-started/eclipselink/docker-compose.yml up -d
+docker compose -p polaris -f getting-started/eclipselink/docker-compose.yml stop spark-sql
+docker compose -p polaris -f getting-started/eclipselink/docker-compose.yml rm -f spark-sql
+docker compose -p polaris -f getting-started/eclipselink/docker-compose.yml up -d --no-deps spark-sql
 ```
 
 Attach to the running spark-sql container:
@@ -237,14 +242,15 @@ org.apache.iceberg.exceptions.ForbiddenException: Forbidden: Principal 'quicksta
 Refresh the Docker container with the user's credentials:
 
 ```shell
-docker compose -f getting-started/eclipselink/docker-compose.yml down trino
-docker compose -f getting-started/eclipselink/docker-compose.yml up -d
+docker compose -p polaris -f getting-started/eclipselink/docker-compose.yml stop trino
+docker compose -p polaris -f getting-started/eclipselink/docker-compose.yml rm -f trino
+docker compose -p polaris -f getting-started/eclipselink/docker-compose.yml up -d --no-deps trino
 ```
 
 Attach to the running Trino container:
 
 ```shell
-docker exec -it eclipselink-trino-1 trino
+docker exec -it $(docker ps -q --filter name=trino) trino
 ```
 
 You may not see Trino's prompt immediately, type ENTER to see it. A few commands that you can try:
