Quickstart

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.

cd ~/polaris
./gradlew \
  :polaris-quarkus-server:assemble \
  :polaris-quarkus-server:quarkusAppPartsBuild \
  :polaris-quarkus-admin:assemble --rerun \
  -Dquarkus.container-image.tag=postgres-latest \
  -Dquarkus.container-image.build=true
docker compose -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:

spark-sql-1          | Spark Web UI available at http://8bc4de8ed854:4040
spark-sql-1          | Spark master: local[*], Application Id: local-1743745174604
spark-sql-1          | 25/04/04 05:39:38 WARN SparkSQLCLIDriver: WARNING: Directory for Hive history file: /home/spark does not exist.   History will not be available during this session.
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:

export CLIENT_ID=root
export CLIENT_SECRET=s3cr3t

The Docker image pre-configures a sample catalog called polaris_demo that uses a local file system.

Running Polaris as a Standalone Process

You can also start Polaris through Gradle (packaged within the Polaris repository):

cd ~/polaris
# Build the server
./gradlew clean :polaris-quarkus-server:assemble :polaris-quarkus-server:quarkusAppPartsBuild --rerun
# Start the server
./gradlew run

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.

When using a Gradle-launched Polaris instance in 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.

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:

export CLIENT_ID=<client-id>
export CLIENT_SECRET=<client-secret>

Installing Apache Spark and Trino Locally for Testing

Apache Spark

If you want to connect to Polaris with Apache Spark, you’ll need to start by cloning Spark. As in the prerequisites, make sure git is installed first.

Then, clone Spark and check out a versioned branch. This guide uses Spark 3.5.

cd ~
git clone https://github.com/apache/spark.git
cd ~/spark
git checkout branch-3.5

Trino

If you want to connect to Polaris with Trino, it is recommended to set up a test instance of Trino using Docker. As in the prerequisites, make sure Docker is installed first

docker run --name trino -d -p 8080:8080 trinodb/trino

Next Steps

Congrats, you now have a running instance of Polaris! For further information regarding how to use Polaris, check out the Using Polaris page.