Server Configuration¶

The Nessie server is configurable via properties as listed in the application.properties file.

These properties can be set when starting up the docker image in two different ways. For example, if you want to set Nessie to use the JDBC version store and provide a JDBC connection URL, you can either:

1. Set these values via the JAVA_OPTS_APPEND option in the Docker invocation. Each setting should be inserted inside the variable’s value as -D<name>=<value> pairs:

   docker run  -p 19120:19120 \
     -e JAVA_OPTS_APPEND="-Dnessie.version.store.type=JDBC -Dquarkus.datasource.jdbc.url=jdbc:postgresql://host.com:5432/db" \
     ghcr.io/projectnessie/nessie
   

2. Alternatively, set them via the --env (or -e) option in the Docker invocation. Each setting must be provided separately as --env NAME=value options:

   docker run -p 19120:19120 \
     --env NESSIE_VERSION_STORE_TYPE=JDBC \
     --env QUARKUS_DATASOURCE_JDBC_URL="jdbc:postgresql://host.com:5432/db" \
     ghcr.io/projectnessie/nessie
   

Note how the original property name is converted to an environment variable, e.g. nessie.version.store.type becomes NESSIE_VERSION_STORE_TYPE. The conversion is done by replacing all . with _ and converting the name to upper case. See here for more details.

For more information on docker images, see Docker image options below.

Server sizing¶

The minimum resources for Nessie are 4 CPUs and 4 GB RAM.

The recommended resources for Nessie depend on the actual use case and usage pattern(s). We recommend to try various configurations, starting with 8 CPUs and 8 GB RAM.

The efficiency of Nessie’s cache can be monitored using the metrics provided with the cache=nessie-objects tag, especially the cache.gets values for hit/miss and the causes provided by cache.evictions.

Supported operating systems¶

Operating System	Production	Development & prototyping	Comments
Linux			Primarily supported operating systems, assuming recent kernel and distribution versions.
macOS			Supported for development and testing purposes.
AIX			Not tested, might work or not.
Solaris			Not tested, might work or not.
Windows			Not supported in any way. Nessie server and admin tool refuse to start.

Providing secrets¶

Instead of providing secrets like passwords in clear text, you can also use a keystore. This functionality is provided natively via Quarkus.

See also the secrets manager settings below for information about Hashicorp Vault, Google Cloud and Amazon Services Secrets Managers.

Core Nessie Configuration Settings¶

Core Settings¶

Nessie server configuration to be injected into the JAX-RS application.

Related Quarkus settings:

Catalog and Iceberg REST Settings¶

Warehouse defaults¶

Warehouses¶

Map of warehouse names to warehouse configurations.

S3 settings¶

Configuration for S3 compatible object stores.

Default settings to be applied to all buckets can be set in the default-options group. Specific settings for each bucket can be specified via the buckets map.

All settings are optional. The defaults of these settings are defined by the AWSSDK Java client.

S3 default bucket settings¶

Default bucket configuration, default/fallback values for all buckets are taken from this one.

S3 per bucket settings¶

Per-bucket configurations. The effective value for a bucket is taken from the per-bucket setting. If no per-bucket setting is present, uses the defaults from the top-level S3 settings in default-options.

S3 transport¶

S3 STS, assume-role global settings¶

Google Cloud Storage settings¶

GCS buckets¶

Configuration for Google Cloud Storage (GCS) object stores.

Default settings to be applied to all buckets can be set in the default-options group. Specific settings for each bucket can be specified via the buckets map.

All settings are optional. The defaults of these settings are defined by the Google Java SDK client.

GCS default bucket settings¶

Default bucket configuration, default/fallback values for all buckets are taken from this one.

GCS per bucket settings¶

Per-bucket configurations. The effective value for a bucket is taken from the per-bucket setting. If no per-bucket setting is present, uses the defaults from the top-level GCS settings in default-options.

GCS transport¶

ADLS settings¶

ADLS default file-system settings¶

Default file-system configuration, default/fallback values for all file-systems are taken from this one.

ADLS per file-system settings¶

Per-bucket configurations. The effective value for a bucket is taken from the per-bucket setting. If no per-bucket setting is present, uses the defaults from the top-level ADLS settings in default-options.

ADLS transport¶

Advanced catalog settings¶

Error Handling¶

Performance Tuning¶

Secrets manager settings¶

Secrets for object stores are strictly separated from the actual configuration entries. This enables the use of external secrets managers. Secrets are referenced using a URN notation.

The URN notation for Nessie secrets is urn:nessie-secret:<provider>:<secret-name>. <provider> references the name of the provider, for example quarkus to resolve secrets via the Quarkus configuration. <secret-name> is the secrets manager specific name for the secret to resolve.

Retrieving secrets from external secrets managers like Hashicorp Vault and the Amazon, Google and Azure secrets managers can take some time. Nessie mitigates this cost by caching retrieved secrets for some time, by default 15 minutes (see config reference below). The default allows you to regularly rotate the object store secrets by updating those in the external secrets manager, Nessie will pick those up within the configured cache TTL. If you do not intent to rotate your secrets, you can bump the TTL to a very high value to prevent cached secrets from being expired and hence perform unneeded requests to secrets managers.

Secrets manager and mapping configuration.

Currently the following secrets managers are supported:

Secrets can always be provided using Quarkus’ built-in mechanisms . Additionally, the following external secrets managers can be enabled:

• VAULT Hashicorp Vault. See the Quarkus docs for Hashicorp Vault for specific information.
• AMAZON AWS Secrets Manager. See the Quarkus docs for Amazon Services / Secrets Manager for specific information.
• AZURE AWS Secrets Manager. NOT SUPPORTED YET! See the Quarkus docs for Azure Key Vault for specific information.
• GOOGLE Google Cloud Secrets Manager. NOT SUPPORTED YET!

For details how secrets are stored, see below

Types of Secrets¶

• Basic credentials are composites of a name attribute and a secret attribute. AWS credentials are managed as basic credentials, where the name represents the access key ID and the secret represents the secret access key.
• Tokens are composites of a token attribute and an optional expiresAt attribute, latter represented as an instant.
• Keys consist of a single key attribute.

Quarkus configuration (incl environment variables)¶

Object store secrets managed via Quarkus’ configuration mechanism (SmallRye Config) resolve components of the secret types (basic credentials, tokens, keys) via individual configuration keys.

The Quarkus configuration key prefix (or environment variable name) is specified for the secret using the URN notation urn:nessie-secret:quarkus:<quarkus-configuration-key-prefix>.<secret-part>.

The following example illustrates the Quarkus configuration entries to define the default S3 access-key and secret-access-key:

# 
#                   Prefix of the Quarkus configuration keys for this secret ---+
#                                                                               |
#                     The URN for Quarkus secrets ---+                          |
#                                                    |                          |
#                                                    |------------------------- |--------------------
nessie.catalog.service.s3.default-options.access-key=urn:nessie-secret:quarkus:my-secrets.s3-default
# The AWS access-key and secret-access-key are referenced via the "secret-part" name,
# see 'Types of Secrets' above.
# `my-secrets.s3-default` is the `secret-part` as in the last part of the above property
my-secrets.s3-default.name=awsAccessKeyId
my-secrets.s3-default.secret=awsSecretAccessKey

Storing Secrets in Hashicorp Vault¶

Secrets in Hashicorp Vault are referenced using the URN prefix urn:nessie-secret:vault: followed by the name/path of the secrets in Hashicorp Vault.

When using Hashicorp Vault make sure to configure the connection settings described in the Quarkus docs.

In Hashicorp Vault, secrets are stored as a map of strings to strings, where the map keys are defined by the type of the secret as mentioned above.

For example, using the vault tool, a basic credential is stored like this:

vault kv put secret/nessie-secrets/... name=the_username secret=the_secret_password

vault kv put secret/nessie-secrets/... name=access_key secret=secret_access_key

A token is stored like this:

vault kv put secret/nessie-secrets/... token=value_of_the_secret_token

vault kv put secret/nessie-secrets/... token=value_of_the_token expiresAt=2024-12-24T18:00:00Z

A key is stored like this:

vault kv put secret/nessie-secrets/... key=value_of_the_secret_key

The paths mentioned above (secret/nessie-secrets/...) contain the path within Hashicorp Vault. Those need to be specified in the Nessie secrets URN notation starting with urn:nessie-secret:vault:.

Storing Secrets in Google Cloud and Amazon Services Secrets Managers and Azure Key Vault¶

Secrets Store specifics:

In Google Cloud and Amazon Services Secrets Managers and Azure Key Vault all secrets are stored as a single string.

Since credentials consist of multiple values, Nessie expects the stored secret to be a JSON encoded object.

Secrets are generally stored as JSON objects representing a map of strings to strings, where the map keys are defined by the type of the secret as mentioned above.

For example, a basic credential has to be stored as JSON like this, without any leading or trailing whitespaces or newlines:

{"name": "mysecret", "secret": "mypassword"}

A token with an expiration date has to be stored as JSON like this, without any leading or trailing whitespaces or newlines, where the expiresAt attribute is only needed for tokens that expire:

{"token": "rkljmnfgoi4jfgoiujh23o4irj", "expiresAt": "2024-06-05T20:38:16Z"}

A key however is always stored as is and not encoded in JSON.

Version Store Settings¶

Version store configuration.

Support for the database specific implementations¶

BigTable Version Store Settings¶

When setting nessie.version.store.type=BIGTABLE which enables Google BigTable as the version store used by the Nessie server, the following configurations are applicable.

Related Quarkus settings:

JDBC Version Store Settings¶

Setting nessie.version.store.type=JDBC2 enables transactional/RDBMS as the version store used by the Nessie server.

Configuration of the datastore will be done by Quarkus and depends on many factors, such as the actual database to use. The property nessie.version.store.persist.jdbc.datasource will be used to select one of the built-in datasources; currently supported values are: postgresql (which activates the PostgresQL driver), mariadb (which activates the MariaDB driver), and mysql (which targets MySQL backends, but using the MariaDB driver).

For example, to configure a PostgresQL connection, the following configuration should be used:

• nessie.version.store.type=JDBC2
• nessie.version.store.persist.jdbc.datasource=postgresql
• quarkus.datasource.postgresql.jdbc.url=jdbc:postgresql://localhost:5432/my_database
• quarkus.datasource.postgresql.username=<your username>
• quarkus.datasource.postgresql.password=<your password>
• Other PostgresQL-specific properties can be set using quarkus.datasource.postgresql.*

To connect to a MariaDB database instead, the following configuration should be used:

• nessie.version.store.type=JDBC2
• nessie.version.store.persist.jdbc.datasource=mariadb
• quarkus.datasource.mariadb.jdbc.url=jdbc:mariadb://localhost:3306/my_database
• quarkus.datasource.mariadb.username=<your username>
• quarkus.datasource.mariadb.password=<your password>
• Other MariaDB-specific properties can be set using quarkus.datasource.mariadb.*

To connect to a MySQL database instead, the following configuration should be used:

• nessie.version.store.type=JDBC2
• nessie.version.store.persist.jdbc.datasource=mysql
• quarkus.datasource.mysql.jdbc.url=jdbc:mysql://localhost:3306/my_database
• quarkus.datasource.mysql.username=<your username>
• quarkus.datasource.mysql.password=<your password>
• Other MySQL-specific properties can be set using quarkus.datasource.mysql.*

To connect to an H2 in-memory database, the following configuration should be used (note that H2 is not recommended for production):

• nessie.version.store.type=JDBC2
• nessie.version.store.persist.jdbc.datasource=h2

Note: for MySQL, the MariaDB driver is used, as it is compatible with MySQL. You can use either jdbc:mysql or jdbc:mariadb as the URL prefix.

A complete set of JDBC configuration options can be found on quarkus.io.

RocksDB Version Store Settings¶

When setting nessie.version.store.type=ROCKSDB which enables RocksDB as the version store used by the Nessie server, the following configurations are applicable.

Cassandra Version Store Settings¶

When setting nessie.version.store.type=CASSANDRA which enables Apache Cassandra or ScyllaDB as the version store used by the Nessie server, the following configurations are applicable.

Related Quarkus settings:

DynamoDB Version Store Settings¶

When setting nessie.version.store.type=DYNAMODB which enables DynamoDB as the version store used by the Nessie server, the following configurations are applicable.

Related Quarkus settings:

MongoDB Version Store Settings¶

When setting nessie.version.store.type=MONGODB2 which enables MongoDB as the version store used by the Nessie server, the following configurations are applicable in combination with nessie.version.store.type.

Related Quarkus settings:

In-Memory Version Store Settings¶

No special configuration options for this store type.

Version Store Advanced Settings¶

The following configurations are advanced configurations for version stores to configure how Nessie will store the data into the configured data store:

Usually, only the cache-capacity should be adjusted to the amount of the Java heap “available” for the cache. The default is conservative, bumping the cache size is recommended.

Authentication settings¶

Configuration for Nessie authentication settings.

Related Quarkus settings:

Authorization settings¶

Configuration for Nessie authorization settings.

Metrics¶

Metrics are published using Micrometer; they are available from Nessie’s management interface (port 9000 by default) under the path /q/metrics. For example, if the server is running on localhost, the metrics can be accessed via http://localhost:9000/q/metrics.

Metrics can be scraped by Prometheus or any compatible metrics scraping server. See: Prometheus for more information.

Additional tags can be added to the metrics by setting the nessie.metrics.tags.* property. Each tag is a key-value pair, where the key is the tag name and the value is the tag value. For example, to add a tag environment=prod to all metrics, set nessie.metrics.tags.environment=prod. Many tags can be added, such as below:

nessie.metrics.tags.service=nessie
nessie.metrics.tags.environment=prod
nessie.metrics.tags.region=us-west-2

Note that by default Nessie adds one tag: application=Nessie. You can override this tag by setting the nessie.metrics.tags.application=<new-value> property.

A standard Grafana dashboard is available in the grafana directory of the Nessie repository [here] (https://github.com/projectnessie/nessie/blob/main/grafana/nessie.json). You can use this dashboard to visualize the metrics scraped by Prometheus. Note that this dashboard is a starting point and may need to be customized to fit your specific needs.

This Grafana dashboard expects the metrics to have a few tags defined: service and instance. The instance tag is generally added by Prometheus automatically, but the service tag needs to be added manually. You can configure Nessie to add this tag to all metrics by setting the below property:

nessie.metrics.tags.service=<service-name>

Alternatively, you can modify the dashboard to remove unnecessary tags, or configure Prometheus to add the missing ones. Here is an example configuration showing how to have the service tag added by Prometheus:

scrape_configs:
  - job_name: 'nessie'
    metrics_path: /q/metrics
    static_configs:
      - targets: ['nessie:9000']
        labels:
          service: nessie

Traces¶

Since Nessie 0.46.0, traces are published using OpenTelemetry. See Using OpenTelemetry in the Quarkus documentation.

In order for the server to enable OpenTelemetry and publish its traces, the quarkus.otel.exporter.otlp.traces.endpoint property must be defined. Its value must be a valid collector endpoint URL, with either http:// or https:// scheme. The collector must talk the OpenTelemetry protocol (OTLP) and the port must be its gRPC port (by default 4317), e.g. “http://otlp-collector:4317”. If this property is not set, the server will not publish traces.

Alternatively, it’s possible to forcibly disable OpenTelemetry at runtime by setting the following property: quarkus.otel.sdk.disabled=true.

Troubleshooting traces¶

If the server is unable to publish traces, check first for a log warning message like the following:

SEVERE [io.ope.exp.int.grp.OkHttpGrpcExporter] (OkHttp http://localhost:4317/...) Failed to export spans. 
The request could not be executed. Full error message: Failed to connect to localhost/0:0:0:0:0:0:0:1:4317

This means that the server is unable to connect to the collector. Check that the collector is running and that the URL is correct.

Swagger UI¶

The Swagger UI allows for testing the REST API and reading the API docs. It is available at SwaggerHub.

Docker image options¶

By default, Nessie listens on port 19120. To expose that port on the host, use -p 19120:19120. To expose that port on a different port on the host system, use the -p option and map the internal port to some port on the host. For example, to expose Nessie on port 8080 of the host system, use the following command:

docker run -p 8080:19120 ghcr.io/projectnessie/nessie

Then you can browse Nessie’s UI on the host by pointing your browser to http://localhost:8080.

Note: this doesn’t change the port Nessie listens on, it only changes the port on the host system that is mapped to the port Nessie listens on. Nessie still listens on port 19120 inside the container. If you want to change the port Nessie listens on, you can use the QUARKUS_HTTP_PORT environment variable. For example, to make Nessie listen on port 8080 inside the container, and expose it to the host system also on 8080, use the following command:

docker run -p 8080:8080 -e QUARKUS_HTTP_PORT=8080 ghcr.io/projectnessie/nessie

Nessie Docker image types¶

Nessie publishes a Java based multiplatform (for amd64, arm64, ppc64le, s390x) image running on OpenJDK 17.

Advanced Docker image tuning (Java images only)¶

There are many environment variables available to configure the Docker image. If in doubt, leave everything at its default. You can configure the behavior using the environment variables listed below, which come from the base image used by Nessie, ubi9/openjdk-21-runtime.

Examples¶

Reference¶

Troubleshooting configuration issues¶

If you encounter issues with the configuration, you can ask Nessie to print out the configuration it is using. To do this, set the log level for the io.smallrye.config category to DEBUG, and also set the console appender level to DEBUG:

quarkus.log.console.level=DEBUG
quarkus.log.category."io.smallrye.config".level=DEBUG