This is an automated email from the ASF dual-hosted git repository.
yufei pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/polaris.git
The following commit(s) were added to refs/heads/main by this push:
new 0eafcaa46 Fix quickstart doc with docker compose (#1610)
0eafcaa46 is described below
commit 0eafcaa4678d85ce9358ba544c02e231b8797eb3
Author: MonkeyCanCode <[email protected]>
AuthorDate: Fri May 23 00:43:33 2025 -0500
Fix quickstart doc with docker compose (#1610)
---
.../assets/postgres/docker-compose-postgres.yml | 2 +-
getting-started/eclipselink/README.md | 7 +++-
.../eclipselink/docker-compose-bootstrap-db.yml | 4 +--
getting-started/eclipselink/docker-compose.yml | 10 +++---
getting-started/jdbc/README.md | 1 +
getting-started/jdbc/docker-compose.yml | 4 +--
.../deploying-polaris/quickstart-deploy-aws.md | 2 ++
.../deploying-polaris/quickstart-deploy-azure.md | 2 ++
.../deploying-polaris/quickstart-deploy-gcp.md | 2 ++
.../unreleased/getting-started/quickstart.md | 41 +++++++++++-----------
.../unreleased/getting-started/using-polaris.md | 16 ++++++---
11 files changed, 55 insertions(+), 36 deletions(-)
diff --git a/getting-started/assets/postgres/docker-compose-postgres.yml
b/getting-started/assets/postgres/docker-compose-postgres.yml
index 393f59fb6..2684b141a 100644
--- 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
index aaeac6371..ed5e5be3f 100644
--- 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
index 5861f5916..7edc91fad 100644
--- 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
index 06f6b3c63..00e53979d 100644
--- 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
index f923ebc72..0d562094c 100644
--- 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
index 67e8f9757..832e0ac62 100644
--- 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
index 7425c6e34..8754408c8 100644
---
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
index f8b75de79..53ab57a9a 100644
---
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
index 86ec4a89f..d76d82b74 100644
---
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
index e04f71cd7..d59d76ac7 100644
--- 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
index 7713b149c..9c01d1c16 100644
--- 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:
