diff --git a/getting-started/assets/postgres/docker-compose-postgres.yml b/getting-started/assets/postgres/docker-compose-postgres.yml index 393f59fb6c..2684b141a9 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 aaeac63714..ed5e5be3f2 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 5861f59166..7edc91fad3 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 06f6b3c63e..00e53979d4 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 f923ebc721..0d562094c7 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 67e8f9757c..832e0ac62d 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 7425c6e344..8754408c87 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 f8b75de79b..53ab57a9a3 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 86ec4a89f0..d76d82b74f 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 e04f71cd73..d59d76ac73 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 7713b149cb..9c01d1c164 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: