Running Polaris and Bootstrapping a Realm

Time: ~6 minutes. Tangible win: locate the bootstrap root principal credentials in your server's startup output — the one seed credential every later call in this course depends on.

A realm is a top-level tenant boundary inside one Polaris deployment — catalogs, principals, and roles all live inside exactly one realm. A single-node quickstart typically runs one realm (commonly named default-realm or POLARIS), but production deployments can host many realms behind one Polaris process for multi-tenancy.

Primary source Polaris Quickstart guide (1.7.0) — the Docker Compose setup this exercise runs against.
There is no default password On first boot, Polaris bootstraps a root principal for the realm and prints its clientId:clientSecret pair to the server logs exactly once. If you lose that line before saving it, you re-bootstrap or rotate credentials through an authenticated admin path — there's no way to recover it after the fact.

The root principal is a real Principal (Lesson 2) with the built-in PRINCIPAL_ROLE:ALL scope — enough to do anything, which is why Lesson 6 immediately creates a narrower, purpose-specific principal instead of using root for everyday work.

Exercise: find your bootstrap line

docker compose up -d
docker logs polaris 2>&1 | grep -i "root principal credentials"

Verified output from a real local run:

realm: default-realm root principal credentials: f103ea289b7df858:<redacted-secret>

Retrieval check

You restart the Polaris container with a fresh (empty) volume. Will last session's root credentials still work?

Correct. Bootstrap credentials are generated per-boot against a given persistence state — a fresh volume means a fresh bootstrap, and the old pair is gone.

Not quite. Credentials aren't baked into the image or tied to the realm name alone — they're generated fresh whenever the underlying state is fresh.

What is a realm's relationship to a catalog?

Correct. Realm sits above Lesson 2's entity tree entirely — it's the tenancy boundary, not a peer of Catalog.

No. A realm is the boundary that contains catalogs, principals, and roles — not interchangeable with "catalog," and a catalog never spans realms.

Practice

  1. Start your own Polaris container and grep the startup log for the bootstrap line.
  2. Save the clientId:clientSecret pair somewhere you can reference for the next three lessons.
  3. State in one sentence what persistence backend your quickstart is using, and whether you'd expect that credential to survive a restart (Lesson 9 covers this properly).
Ask the agent: "If I need a second admin identity besides root, do I bootstrap a new realm or just create another principal in this one?" Next lesson uses this credential to make your first real Iceberg REST Catalog calls.