Installation#

Install and configure Starburst Portal using one of the following methods:

tar.gz archive
Helm

Requirements#

Before you install Starburst Portal, ensure you have the following:

A valid SEP license
A supported backend database
For tar.gz installation: a Linux server (x86_64 or AArch64 architecture)
For Helm installation: a Kubernetes cluster with kubectl and Helm

Backend database#

Starburst Portal requires a backend database for persistence. You must provision and configure the database before you start Starburst Portal. Use one of the following databases:

MySQL
PostgreSQL
Oracle

Create a dedicated database and user for Starburst Portal.

On startup, Starburst Portal automatically initializes your database and runs any required schema migrations.

For a list of available database configuration properties, see Backend database configuration.

Install with `tar.gz` archive#

Use the following steps to install Starburst Portal using the tar.gz archive.

Download the archive#

Download the tar.gz archive for your platform from Starburst software downloads:

Use starburst-portal-<version>-x86_64.tar.gz for x86_64 systems
Use starburst-portal-<version>-aarch64.tar.gz for ARM64 systems

Extract and install the archive#

Extract the archive:

tar -xzf starburst-portal-<version>-<arch>.tar.gz

Move the archive to the installation directory:

sudo mv starburst-portal-<version>-<arch> /usr/lib/starburst-portal

Create a configuration directory:

sudo mkdir -p /etc/starburst

Directories#

The archive contains the following directories:

starburst-portal/
|-- bin/                    # Launcher executable
|-- jvm/                    # Bundled JDK
|-- lib/                    # Application JAR files
+-- secrets-plugin/         # Secrets provider plugin

Create configuration files#

Create the main configuration file at /etc/starburst/config.properties:

# Node configuration
node.environment=production

# HTTP server
http-server.http.enabled=true
http-server.http.port=8080

# Database persistence
persistence.jdbc.url=jdbc:postgresql://your-database-url:5432/starburst_portal
persistence.jdbc.user=starburst_portal
persistence.jdbc.password=your-secure-password

# Gateway configuration
gateway.enabled=true
gateway.clusters.enabled=true
gateway.clusters.encryption.secret=your-encryption-secret

# Catalog
catalog.enabled=true
credentials-provider.type=file
credentials-provider.credentials-file-path=/etc/starburst/catalog-credentials.json

Create the catalog credentials file at /etc/starburst/catalog-credentials.json:

[
  {
    "emulated": {
      "accessKey": "your-emulated-access-key",
      "secretKey": "your-emulated-secret-key"
    }
  }
]

Create JVM configuration at /etc/starburst/jvm.config:

-server
-XX:InitialRAMPercentage=80
-XX:MaxRAMPercentage=80
-XX:+ExplicitGCInvokesConcurrent
-XX:+HeapDumpOnOutOfMemoryError
-XX:+ExitOnOutOfMemoryError
-Djdk.attach.allowAttachSelf=true
-Dfile.encoding=UTF-8

Create logging configuration at /etc/starburst/log.properties:

io.starburst=INFO
io.trino=INFO

For more information about each configuration file, see Configuration files.

Copy license file#

Copy your Starburst license file to the configuration directory:

sudo cp starburstdata.license /etc/starburst/

Start Starburst Portal#

To start Starburst Portal, use the following command:

/usr/lib/starburst-portal/bin/launcher run --etc-dir /etc/starburst

To run Starburst Portal as a background service, use the following command:

/usr/lib/starburst-portal/bin/launcher start --etc-dir /etc/starburst

Install with Helm#

Use the following steps to deploy Starburst Portal on Kubernetes with Helm.

Configure Harbor registry access#

To log in to the Starburst Harbor registry, use the following command:

helm registry login "harbor.starburstdata.net" \
  --username "<your-registry-username>" \
  --password "<your-registry-password>"

To verify your registry access, use the following command:

helm pull oci://harbor.starburstdata.net/starburstdata/charts/starburst-portal --version <version>

Create image pull secret#

Create a Docker registry secret for the private registry:

kubectl create secret docker-registry regcred \
  --docker-server="https://harbor.starburstdata.net" \
  --docker-username="<your-registry-username>" \
  --docker-password="<your-registry-password>"

Create configuration secrets#

Create a Kubernetes secret for the license:

kubectl create secret generic starburst \
  --from-file=starburstdata.license=./starburstdata.license

Create a secret for sensitive configuration values:

kubectl create secret generic portal-secret \
  --from-literal=DB_PASSWORD='your-secure-password' \
  --from-literal=CLUSTERS_ENCRYPTION_SECRET='your-encryption-secret'

Create configuration file#

Create a portal-values.yaml file with your configuration:

imagePullSecrets:
  - name: regcred

etcFiles:
  config: |
    # Node identification
    node.environment=production

    # Database (required)
    persistence.jdbc.url=jdbc:postgresql://starburst-persistence-postgresql:5432/starburst_portal
    persistence.jdbc.user=starburst_portal
    persistence.jdbc.password=${ENV:DB_PASSWORD}

    # Gateway configuration
    gateway.enabled=true
    gateway.clusters.encryption.secret=${ENV:CLUSTERS_ENCRYPTION_SECRET}

  catalogCredentials: |
    [
      {
        "emulated": {
          "accessKey": "your-emulated-access-key",
          "secretKey": "your-emulated-secret-key"
        }
      }
    ]

envFrom:
  - secretRef:
      name: portal-secret

Deploy Starburst Portal#

To deploy Starburst Portal, use the following command:

helm install starburst-portal \
  oci://harbor.starburstdata.net/starburstdata/charts/starburst-portal \
  -f portal-values.yaml

Verify deployment#

To verify your deployment, use the following command:

kubectl get pods -l app=starburst-portal
kubectl logs -l app=starburst-portal

Configuration#

Use the following sections to configure Starburst Portal.

Minimal configuration#

The following properties are required for a minimal working configuration:

# Node identification
node.environment=production

# Database (required)
persistence.jdbc.url=jdbc:postgresql://hostname:5432/database
persistence.jdbc.user=username
persistence.jdbc.password=password

# Gateway with cluster management
gateway.enabled=true
gateway.clusters.encryption.secret=secret-key

Backend database configuration#

Use the following properties to configure the backend database:

Backend database configuration properties#
Property	Description	Default
`persistence.jdbc.url`	JDBC connection URL for the Starburst Portal backend database. The URL must include the protocol, hostname, port, and database name. The supported formats are: PostgreSQL: `jdbc:postgresql://hostname:5432/database_name` MySQL: `jdbc:mysql://hostname:3306/database_name` Oracle: `jdbc:oracle:thin:@hostname:1521:database_name`	None (required)
`persistence.jdbc.user`	Username for authenticating to the database. This user must have permissions to create and modify tables for schema migrations.	None (required)
`persistence.jdbc.password`	Password for the database user. For production deployments, use secrets substitution such as `${ENV:VAR_NAME}`.	None (required)
`persistence.query-history.retention-time`	Duration to retain query history records. Starburst Portal automatically deletes older records. Use `h` for hours or `d` for days.	`4h`

Cluster configuration#

Use the following properties to configure how Starburst Portal manages and routes queries to clusters. Manage individual cluster configurations through the Starburst Portal UI.

Property	Description	Default
`gateway.enabled`	Enables the gateway functionality and allows Starburst Portal to route queries to backend clusters. This property is required for cluster management features.	`false`
`gateway.clusters.enabled`	Enables UI-based cluster management. When you enable this property, Starburst Portal stores cluster configurations in the database.	`true`
`gateway.clusters.encryption.secret`	Secret key that encrypts cluster credentials stored in the database. Keep this value secure and consistent across restarts.	None (required)
`gateway.clusters.monitoring.refresh-interval`	Interval between health check requests to registered clusters. Lower values provide faster detection of cluster failures but increase network traffic.	`30s`
`gateway.load-balancing.strategy`	Algorithm that distributes queries across healthy clusters in a routing group. Choose between the following strategies: `RANDOM`: Distribute queries randomly across healthy clusters `QUERY_COUNT_BASED`: Route based on active query count	`RANDOM`

HTTPS configuration#

To enable HTTPS, add the following properties to your configuration file:

http-server.http.enabled=false
http-server.https.enabled=true
http-server.https.port=8443
http-server.https.keystore.path=/etc/starburst/keystore.jks
http-server.https.keystore.key=keystore-password

Health checks#

Use the following endpoints to monitor the health of your Starburst Portal instance:

Liveness: GET /status/livez
- Returns 200 when the process is running
Readiness: GET /status/readyz
- Returns 200 when Starburst Portal is ready to serve requests

Configuration files#

Use the following files to configure Starburst Portal for tar.gz installations:

File	Purpose
`/etc/starburst/config.properties`	Main configuration file for Starburst Portal. Contains database connection, gateway configuration, authentication, and HTTP server settings.
`/etc/starburst/catalog-credentials.json`	JSON file that contains credentials for AWS authentication when accessing the Glue API for catalog operations.
`/etc/starburst/jvm.config`	JVM startup options including memory settings, garbage collection, and system properties. Specify one option per line.
`/etc/starburst/log.properties`	Logging level configuration for different packages. Controls verbosity of logs for troubleshooting and monitoring.
`/etc/starburst/starburstdata.license`	Starburst license file. Obtain from your Starburst representative or the software downloads portal.