MonkeyCanCode commented on code in PR #1013: URL: https://github.com/apache/polaris/pull/1013#discussion_r1958614652
########## site/content/in-dev/unreleased/quickstart.md: ########## @@ -1,351 +1,8 @@ ---- -# -# 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: Quick Start -type: docs -weight: 100 ---- - -This guide serves as a introduction to several key entities that can be managed with Apache Polaris (Incubating), describes how to build and deploy Polaris locally, and finally includes examples of how to use Polaris with Apache Spark™. - -## Prerequisites - -This guide covers building Polaris, deploying it locally or via [Docker](https://www.docker.com/), and interacting with it using the command-line interface and [Apache Spark](https://spark.apache.org/). Before proceeding with Polaris, be sure to satisfy the relevant prerequisites listed here. - -### Building and Deploying Polaris - -To get the latest Polaris code, you'll need to clone the repository using [git](https://git-scm.com/). You can install git using [homebrew](https://brew.sh/): - -```shell -brew install git -``` - -Then, use git to clone the Polaris repo: - -```shell -cd ~ -git clone https://github.com/apache/polaris.git -``` - -#### With Docker - -If you plan to deploy Polaris inside [Docker](https://www.docker.com/), you'll need to install docker itself. For example, this can be done using [homebrew](https://brew.sh/): - -```shell -brew install --cask docker -``` - -There could be a [Docker permission issues](https://github.com/apache/polaris/pull/971) related to seccomp configuration. To resolve these issues, set the `seccomp` profile to "unconfined" when running a container.For example: - -```shell -docker run --security-opt seccomp=unconfined apache/polaris:latest -``` - -Note: Setting the seccomp profile to "unconfined" disables the default system call filtering, which may pose security risks. Use this configuration with caution, especially in production environments. - -Once installed, make sure Docker is running. - -#### From Source - -If you plan to build Polaris from source yourself, you will need to satisfy a few prerequisites first. - -Polaris is built using [gradle](https://gradle.org/) and is compatible with Java 21. We recommend the use of [jenv](https://www.jenv.be/) to manage multiple Java versions. For example, to install Java 21 via [homebrew](https://brew.sh/) and configure it with jenv: - -```shell -cd ~/polaris -brew install openjdk@21 jenv -jenv add $(brew --prefix openjdk@21) -jenv local 21 -``` - -### Connecting to Polaris - -Polaris is compatible with any [Apache Iceberg](https://iceberg.apache.org/) client that supports the REST API. Depending on the client you plan to use, refer to the prerequisites below. - -#### With Spark - -If you want to connect to Polaris with [Apache Spark](https://spark.apache.org/), you'll need to start by cloning Spark. As [above](#building-and-deploying-polaris), make sure [git](https://git-scm.com/) is installed first. You can install it with [homebrew](https://brew.sh/): - -```shell -brew install git -``` - -Then, clone Spark and check out a versioned branch. This guide uses [Spark 3.5](https://spark.apache.org/releases/spark-release-3-5-0.html). - -```shell -cd ~ -git clone https://github.com/apache/spark.git -cd ~/spark -git checkout branch-3.5 -``` - -## Deploying Polaris - -Polaris can be deployed via a lightweight docker image or as a standalone process. Before starting, be sure that you've satisfied the relevant [prerequisites](#building-and-deploying-polaris) detailed above. - -### Docker Image - -To start using Polaris in Docker, launch Polaris while Docker is running: - -```shell -cd ~/polaris -./gradlew clean :polaris-quarkus-server:assemble -Dquarkus.container-image.build=true -docker run -p 8181:8181 -p 8182:8182 apache/polaris:latest -``` - -You should see output for some time as Polaris builds and starts up. Eventually, you won’t see any more logs and should see messages that resemble the following: - -``` -INFO [io.quarkus] [,] [,,,] (Quarkus Main Thread) Apache Polaris Server <version> on JVM (powered by Quarkus <version>) started in 2.656s. Listening on: http://localhost:8181. Management interface listening on http://0.0.0.0:8182. -INFO [io.quarkus] [,] [,,,] (Quarkus Main Thread) Profile prod activated. -INFO [io.quarkus] [,] [,,,] (Quarkus Main Thread) Installed features: [...] -``` - -### Running Polaris as a Standalone Process - -The easiest way to run Polaris locally is to start the Polaris server from the -`quarkus/server/build` directory (after building Polaris): - -```shell -cd ~/polaris -# Build the server -./gradlew clean :polaris-quarkus-server:assemble -# Start the server -java -jar quarkus/server/build/quarkus-app/quarkus-run.jar -``` - -You should see output for some time as Polaris builds and starts up. Eventually, you won’t see any more logs and should see messages that resemble the following: - -``` -realm: <realm> root principal credentials: <client-id>:<client-secret> -INFO [io.quarkus] [,] [,,,] (Quarkus Main Thread) polaris-quarkus-service <version> on JVM (powered by Quarkus <version>) started in 2.656s. Listening on: http://localhost:8181. Management interface listening on http://0.0.0.0:8182. -INFO [io.quarkus] [,] [,,,] (Quarkus Main Thread) Profile prod activated. Live Coding activated. -INFO [io.quarkus] [,] [,,,] (Quarkus Main Thread) Installed features: [...] -``` - -At this point, Polaris is running. - -For this tutorial, we'll launch an instance of Polaris that stores entities only in-memory. This means that any entities that you define will be destroyed when Polaris is shut down. It also means that Polaris will automatically bootstrap itself with root credentials. For more information on how to configure Polaris for production usage, see the [docs]({{% ref "configuring-polaris-for-production" %}}). - -When Polaris is launched using an in-memory metastore, the root principal credentials can be found -in stdout on initial startup. Look for a line that resembles the following: - -``` -realm: <realm> root principal credentials: <client-id>:<client-secret> -``` - -Be sure to take note of these credentials as we'll be using them below. You can also set these credentials as environment variables for use with the Polaris CLI: - -```shell -export CLIENT_ID=<client-id> -export CLIENT_SECRET=<client-secret> -``` +# Quick Start (Deprecated) Review Comment: Assuming we would want to proceed with this, we still need to keep the license header. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
