Deploy and Host

A self-hosted Apache Iceberg REST catalog powered by Apache Polaris 1.7.0, with PostgreSQL persistence and S3-compatible storage. Includes a password-protected dashboard, namespace/table browsing, connection instructions, and automatic warehouse initialization.

About Hosting

This template provisions three resources: a catalog service built from the Dockerfile, a PostgreSQL database for catalog and authorization state, and a Railway Bucket for Iceberg metadata, manifests, and data files. The catalog service runs Polaris on loopback and a Python dashboard that proxies API requests. No volume is needed on the catalog service; PostgreSQL and the bucket persist all state.

Why Deploy

Deploying this template gives you a production-ready Iceberg REST catalog in minutes. Polaris handles OAuth2 authentication, catalog management, and namespace/table metadata. The dashboard provides a friendly UI for browsing namespaces and tables and for connecting Iceberg clients. Automatic warehouse initialization means the catalog is ready to use immediately after deployment.

Common Use Cases

Hosting an Iceberg REST catalog for Spark, Trino, or PyIceberg clients
Managing multiple namespaces and tables with a web dashboard
Storing Iceberg metadata and data files in S3-compatible object storage
Building a data platform foundation with OAuth2-secured catalog access

Dependencies for Deployment

PostgreSQL: catalog and authorization state
Railway Bucket (S3-compatible): Iceberg metadata, manifests, and data files
GitHub repository: impacte-tech/polaris-template

Connect an Iceberg client

Setting	Value
REST URI	`https:///api/catalog`
OAuth token endpoint	`https:///api/catalog/v1/oauth/tokens`
Warehouse	`warehouse` (or your `CATALOG_NAME`)
Credential	`:`
Scope	`PRINCIPAL_ROLE:ALL`

Operations

Credentials: Changing POLARIS_CLIENT_SECRET does not rotate credentials in an existing database. Rotate/reset them through Polaris's management API and update the Railway variable to match.
Backups: Back up PostgreSQL and object storage. One without the other is insufficient to restore your tables.
Upgrades: Both Polaris images are pinned to 1.7.0. Test upgrades with a database backup and run any schema migrations required by the release.

Deploy apache polaris: iceberg catalog template