Polaris Console

July 4, 2026 · View on GitHub

A modern web interface for Apache Polaris, built with React, TypeScript, TanStack Query, and Tailwind CSS.

Getting Started

Prerequisites

Node.js 20.19+ (or 22.13+) and npm (or yarn)

Installation

# Install dependencies
make install

# Start development server
make dev

# Build for production
make build

Environment Variables

Create a .env file based on .env.example:

# Required
VITE_POLARIS_API_URL=http://localhost:8181
VITE_POLARIS_REALM=POLARIS
VITE_POLARIS_PRINCIPAL_SCOPE=PRINCIPAL_ROLE:ALL

# Optional
VITE_POLARIS_REALM_HEADER_NAME=Polaris-Realm  # defaults to "Polaris-Realm"
VITE_OAUTH_TOKEN_URL=http://localhost:8181/api/catalog/v1/oauth/tokens  # defaults to ${VITE_POLARIS_API_URL}/api/catalog/v1/oauth/tokens

# OIDC Authentication (optional)
VITE_OIDC_ISSUER_URL=http://localhost:8080/realms/EXTERNAL
VITE_OIDC_CLIENT_ID=polaris-console
VITE_OIDC_REDIRECT_URI=http://localhost:5173/auth/callback
VITE_OIDC_SCOPE=openid profile email

Note: The console makes direct API calls to the Polaris server. Ensure CORS is properly configured on the server (see below).

Server-Side CORS Configuration

The console makes direct API calls to the Polaris server. Configure CORS on your Polaris server (Quarkus-based).

Option 1: Using application.properties

Add to your Polaris application.properties file:

quarkus.http.cors.enabled=true
quarkus.http.cors.origins=https://console.polaris.service
quarkus.http.cors.methods=GET,POST,PUT,DELETE,PATCH,OPTIONS
quarkus.http.cors.headers=Content-Type,Authorization,Polaris-Realm
quarkus.http.cors.exposed-headers=*
quarkus.http.cors.access-control-allow-credentials=true
quarkus.http.cors.access-control-max-age=PT10M

Option 2: Using Environment Variables

Set these environment variables:

QUARKUS_HTTP_CORS_ENABLED=true
QUARKUS_HTTP_CORS_ORIGINS=https://console.polaris.service
QUARKUS_HTTP_CORS_METHODS=GET,POST,PUT,DELETE,PATCH,OPTIONS
QUARKUS_HTTP_CORS_HEADERS=Content-Type,Authorization,Polaris-Realm,X-Request-ID
QUARKUS_HTTP_CORS_EXPOSED_HEADERS=*
QUARKUS_HTTP_CORS_ACCESS_CONTROL_ALLOW_CREDENTIALS=true
QUARKUS_HTTP_CORS_ACCESS_CONTROL_MAX_AGE=PT10M

Option 3: Using Kubernetes ConfigMap

For Kubernetes/Helm deployments you need configure cors section in values.yaml:

cors:
   enabled: true
   allowedOrigins:
      - "https://console.polaris.service"
   allowedMethods:
      - "GET"
      - "POST"
      - "PUT"
      - "DELETE"
      - "PATCH"
      - "OPTIONS"
   allowedHeaders:
      - "Content-Type"
      - "Authorization"
      - "Polaris-Realm"
      - "X-Request-ID"
   exposedHeaders:
      - "*"
   accessControlMaxAge: "PT10M"
   accessControlAllowCredentials: true

See Quarkus CORS documentation for more details.

Authentication

The console supports two authentication methods:

1. Client Credentials (Default)

Standard OAuth 2.0 client credentials flow using username/password. This is the default authentication method.

2. OIDC Authentication (Optional)

The console supports OpenID Connect (OIDC) authentication with PKCE flow. When configured, users can authenticate using an external identity provider (e.g., Keycloak, Auth0, Okta).

OIDC Configuration

Set these environment variables to enable OIDC:

VITE_OIDC_ISSUER_URL=http://keycloak:18080/realms/EXTERNAL
VITE_OIDC_CLIENT_ID=polaris-console
VITE_OIDC_REDIRECT_URI=http://localhost:5173/auth/callback
VITE_OIDC_SCOPE=openid profile email

Configuration Details:

VITE_OIDC_ISSUER_URL: Your OIDC provider's issuer URL. The console will automatically discover endpoints using .well-known/openid-configuration
VITE_OIDC_CLIENT_ID: Client ID registered with your OIDC provider
VITE_OIDC_REDIRECT_URI: Callback URL where the OIDC provider redirects after authentication (must match your app URL + /auth/callback)
VITE_OIDC_SCOPE: OAuth scopes to request (typically openid profile email)

OIDC Provider Setup (Keycloak Example)

Create a new client in Keycloak
Set Client ID to match VITE_OIDC_CLIENT_ID
Set Access Type to public (PKCE flow)
Add Valid Redirect URIs: http://localhost:5173/auth/callback
Enable Standard Flow (Authorization Code Flow)
Configure token claims to include user principal information

Note: Both the console and Polaris server must use the same OIDC provider. Also, use port 18080 for Keycloak, as port 8080 is being used by the Polaris console.

Project Structure

src/
├── api/              # API client and endpoints
│   ├── client.ts     # Axios instance with interceptors
│   ├── auth.ts       # Authentication API
│   └── management/   # Management Service APIs
├── components/        # React components
│   ├── ui/           # Shadcn UI components
│   ├── layout/       # Layout components
│   └── forms/        # Form components
├── hooks/            # Custom React hooks
├── lib/              # Utilities
├── pages/            # Page components
├── types/            # TypeScript type definitions
└── App.tsx           # Main app component

Technology Stack

Framework: React 19 with TypeScript
Routing: React Router v7
State Management: TanStack Query (React Query)
Tables: TanStack Table (React Table)
Styling: Tailwind CSS
Components: Shadcn UI (Radix UI primitives)
Forms: React Hook Form with Zod validation
HTTP Client: Axios
Icons: Lucide React

Development

The project uses:

Vite for fast development and building
ESLint for code linting
TypeScript for type safety

To start developing:

make dev

The app will be available at http://localhost:5173

Building

make build

Output will be in the dist/ directory.

Production Deployment

After building, you can serve the production files in several ways:

Quick Test

bun run preview  # or npm run preview

Docker image

You can build Polaris Console docker image using:

make build-docker

Then, you run Polaris Console using:

docker run -p 8080:8080 \
  -e VITE_POLARIS_API_URL=http://polaris:8181 \
  -e VITE_POLARIS_REALM=POLARIS \
  -e VITE_POLARIS_PRINCIPAL_SCOPE=PRINCIPAL_ROLE:ALL \
  apache/polaris-console:latest

To enable OIDC authentication, add OIDC environment variables:

docker run -p 8080:8080 \
  -e VITE_POLARIS_API_URL=http://polaris:8181 \
  -e VITE_POLARIS_REALM=POLARIS \
  -e VITE_POLARIS_PRINCIPAL_SCOPE=PRINCIPAL_ROLE:ALL \
  -e VITE_OIDC_ISSUER_URL=http://keycloak:18080/realms/EXTERNAL \
  -e VITE_OIDC_CLIENT_ID=polaris-console \
  -e VITE_OIDC_REDIRECT_URI=http://localhost:8080/auth/callback \
  -e VITE_OIDC_SCOPE="openid profile email" \
  apache/polaris-console:latest

NB: Hopefully, the Apache Polaris official docker image will be available soon.

K8S Deployment with Helm

You can check the Apache Polaris documentation and start Polaris instance in polaris namespace via helm.

Quick Start with Minikube

Start Minikube:

minikube start
eval $(minikube docker-env)

Build the image:
```
make build-docker
```

Deploy with Helm:

helm install polaris-console ./helm -n polaris

Access the console:

kubectl port-forward svc/polaris-console 8080:8080 -n polaris

Open http://localhost:8080 in your browser.

Configuration

Customize the deployment by creating a values.yaml file:

config:
  api:
    polarisApiUrl: "http://polaris:8181"
    polarisRealm: "POLARIS"
    oauthTokenUrl: "http://polaris:8181/api/catalog/v1/oauth/tokens"
  # OIDC Configuration (optional)
  oidc:
    issuerUrl: "http://keycloak:18080/realms/EXTERNAL"
    clientId: "polaris-console"
    redirectUri: "http://localhost:8080/auth/callback"
    scope: "openid profile email"

service:
  type: ClusterIP
  ports:
    - name: http
      port: 8080

replicaCount: 1

Then deploy with:

helm install polaris-console ./helm -f values.yaml -n polaris

Useful Commands

# Upgrade deployment
helm upgrade polaris-console ./helm -n polaris

# Uninstall
helm uninstall polaris-console -n polaris

# View logs
kubectl logs -l app.kubernetes.io/name=polaris-console -n polaris