Iglu Server configuration reference
CDI customers
If you're a Snowplow CDI customer, you don't need to manage Iglu directly — it's included in your pipeline. Use Event Studio or the Snowplow CLI to manage your schemas. This page is for Self-Hosted customers.
This is a complete list of the options that can be configured in the Iglu Server HOCON config file. The examples on GitHub show how to prepare this file.
License
Iglu Server is released under the Snowplow Limited Use License (FAQ).
To accept the terms of license and run Iglu Server, set the ACCEPT_LIMITED_USE_LICENSE=yes environment variable. Alternatively, you can configure the license.accept option, like this:
hcl
license {
accept = true
}
Common options
| parameter | description |
|---|---|
repoServer.interface | Optional. Default: 0.0.0.0. Address on which the server listens to http connections. |
repoServer.port | Optional. Default: 8080. Port on which the server listens. |
repoServer.idleTimeout | Default: 30 seconds. TCP connections are dropped after this timeout expires. In case Iglu Server runs behind a load balancer, this should slightly exceed the load balancer's idle timeout. |
repoServer.hsts.enable (since 0.12.0) | Default: false. Whether to send an HSTS header. |
repoServer.hsts.maxAge (since 0.12.0) | Default: 365 days. The maximum age for the HSTS header. |
repoServer.maxPayloadSize (since 0.14.0) | Default: 100000. Maximum accepted request body size in bytes. Requests exceeding this are rejected. |
database.type | Optional. Default: postgres. Can be changed to dummy during development for in-memory only storage. |
database.host | Required. Host name for Postgres database. |
database.port | Optional. Default: 5432. Port for Postgres database. |
database.dbname | Required. Name of Postgres database. |
database.username | Required. Username for connecting to Postgres. |
database.password | Required. Password for connecting to Postgres. |
database.enableStartupChecks | Optional. Default: true. Whether to ping Postgres during startup and fail immediately if it isn't available. Recommended for production, so the instance isn't considered healthy until the Postgres connection is healthy. |
swagger.baseUrl | Optional. Example: /custom/prefix. Customize the api base url in Swagger. Helpful for when running Iglu Server behind a proxy server. |
debug | Optional. Default: true. Enable the additional /api/debug endpoint, which responds with all internal state. |
patchesAllowed | Optional. Default: false. If true, allows overwriting a given version of a schema with new content. See amending schemas. |
webhooks.schemaPublished | Optional. Array with the list of webhooks that will be called when a schema is published or updated with a vendor that matches the specified prefixes. See the examples on GitHub. |
webhooks.schemaPublished.uri | Required. URI of the HTTP server that will receive the webhook event. |
webhooks.schemaPublished.vendorPrefixes | Optional. Example: ["com", "org.acme", "org.snowplow"]. List of schema prefixes (regexes) that should be sent via the webhook. |
webhooks.schemaPublished.usePost (since 0.8.7) | Optional. Default: false. Whether to use POST to send request via the webhook. |
superApiKey | Optional. Set a super api key with permission to read/write any schema, and add other api keys. |
maxJsonDepth (since 0.14.0) | Default: 40. Maximum nesting depth for JSON values accepted by the server. Used both when validating schemas and when parsing incoming JSON payloads. |
Advanced options
These advanced options have sensible defaults and rarely need changing.
| parameter | description |
|---|---|
repoServer.threadPool.type | Default: fixed for a fixed thread pool. Can be cached for a cached thread pool, or global for the global execution context. Type of the thread pool used by the HTTP server and the webhooks HTTP client. |
repoServer.threadPool.size | Optional. Default: 4. Size of the thread pool if the type is fixed. |
repoServer.maxConnections | Optional. Default: 1024. Maximum number of client connections that may be active at any time. |
database.pool.type | Optional. Default: hikari (recommended for production). Can be changed to nopool to remove the upper bound on the number of connections. |
database.pool.maximumPoolSize | Optional. Default: 5. Maximum number of connections in the Hikari pool. |
database.pool.connectionTimeout | Optional. Default: 30 seconds. Timeout on the Hikari connection pool. |
database.pool.maxLifetime | Optional. Default: 1800 seconds. Maximum lifetime of a connection in the Hikari pool. |
database.pool.minimumIdle | Optional. Default: 5. Minimum number of idle connections in the Hikari pool. |
database.pool.connectionPool.type | Optional. Default: fixed for a fixed thread pool (recommended in production). Type of the thread pool used for awaiting connection to the database. |
database.pool.connectionPool.size | Optional. Default: 4. Number of threads to use when the connection pool has type fixed. |
database.driver | Optional. Default: org.postgresql.Driver. JDBC driver class used to connect to Postgres. |
preTerminationPeriod (since 0.8.0) | Optional. Default: 1 second. How long the server should pause after receiving a sigterm before starting the graceful shutdown. During this period the server continues to accept new connections and respond to requests. |
preTerminationUnhealthy (since 0.8.0) | Optional. Default: false. During the preTerminationPeriod, the server can be configured to return 503s on the /health endpoint. Can be helpful for removing the server from a load balancer's targets. |
The database.pool.transactionPool (Hikari) and database.pool.threadPool (nopool) options were removed in 0.15.0: blocking JDBC calls now run on the blocking pool of the runtime. Configurations that still set them keep loading, and the values are ignored. See the 0.15.x upgrade guide.