Configuration Reference

Complete configuration reference for Data Index service and Quarkus Flow applications.

Data Index Service Configuration

Storage Backend Selection

Data Index supports multiple storage backends via separate Maven modules. Each module includes only its backend-specific dependencies.

Project structure:

data-index-service/               # Parent POM (aggregator only)
├── data-index-service-core/      # Common code (GraphQL API, REST)
├── data-index-service-postgresql/  # PostgreSQL backend module
└── data-index-service-elasticsearch/  # Elasticsearch backend module (future)

Backend selection: Navigate to the module you want and build it directly.

PostgreSQL (production-ready):

cd data-index/data-index-service/data-index-service-postgresql
mvn quarkus:dev

Elasticsearch (future):

cd data-index/data-index-service/data-index-service-elasticsearch
mvn quarkus:dev

How it works:

Each service module has its own pom.xml with backend-specific dependencies hardcoded
Each service module has its own application.properties with backend-specific configuration
Common configuration is in data-index-service-core/src/main/resources/application.properties
No Maven or Quarkus profiles needed for backend selection

Configuration files:

data-index-service-core/src/main/resources/application.properties - Common config (GraphQL, HTTP, health, metrics)
data-index-service-postgresql/src/main/resources/application.properties - PostgreSQL-specific config
data-index-service-elasticsearch/src/main/resources/application.properties - Elasticsearch-specific config (placeholder)

Maven profiles:

Only one Maven profile exists: dev-flyway in the PostgreSQL module.

dev-flyway profile - Adds: data-index-storage-migrations, quarkus-flyway
Activated by default (deactivated with -DskipFlyway=true for production)
Development and test builds include Flyway for automatic schema migrations
Production builds exclude Flyway to reduce image size

Each module includes only its backend’s dependencies, keeping deployment size minimal.

Development Mode

Quarkus Dev Services auto-starts storage backends in Docker - no manual database setup required.

Start development with PostgreSQL:

cd data-index/data-index-service/data-index-service-postgresql
mvn quarkus:dev

What happens automatically:

Quarkus loads application.properties from the postgresql module
Dev Services starts postgres:15 container
Flyway runs migrations from data-index-storage-migrations module
Service starts on localhost:8080
Documentation available at localhost:8080/docs

Dev Services PostgreSQL configuration:

Container: postgres:15
Database: dataindex
Username: dataindex
Password: dataindex123
Automatic schema creation via Flyway migrations (dev mode only)
Container auto-starts with dev mode, auto-stops on exit

Live coding enabled: Code changes trigger automatic rebuild and restart.

Access points: * Application: localhost:8080 * GraphQL UI: localhost:8080/q/graphql-ui * Documentation: localhost:8080/docs * Health: localhost:8080/q/health * Metrics: localhost:8080/q/metrics

Production Mode

Build for production:

# Build PostgreSQL backend (excludes Flyway)
cd data-index/data-index-service/data-index-service-postgresql
mvn clean package -DskipFlyway=true -DskipTests

# Result: target/quarkus-app/ (optimized Quarkus app)
# Container image: kubesmarts/data-index-service-postgresql:999-SNAPSHOT

Build Elasticsearch backend (future):

cd data-index/data-index-service/data-index-service-elasticsearch
mvn clean package -DskipFlyway=true -DskipTests

Why skip Flyway?

Flyway and migration SQL files are only needed in development (Dev Services)
Production deployments initialize schema manually using SQL scripts
Skipping Flyway reduces container image size
The -DskipFlyway=true flag deactivates the dev-flyway Maven profile

Container image build:

cd data-index/data-index-service/data-index-service-postgresql
mvn package -DskipFlyway=true \
  -Dquarkus.container-image.build=true \
  -DskipTests

Runtime configuration (via environment variables):

# Required - overrides Dev Services
QUARKUS_DATASOURCE_JDBC_URL=jdbc:postgresql://postgresql.postgresql.svc.cluster.local:5432/dataindex
QUARKUS_DATASOURCE_USERNAME=dataindex
QUARKUS_DATASOURCE_PASSWORD=***

# Optional - already configured with defaults
QUARKUS_DATASOURCE_JDBC_MAX_SIZE=20
QUARKUS_DATASOURCE_JDBC_MIN_SIZE=5

How it works:

When QUARKUS_DATASOURCE_JDBC_URL is set, Dev Services is automatically disabled
Application connects to the provided PostgreSQL instance
Schema must be initialized manually using SQL migration scripts

Database schema management in production:

Flyway is disabled in production (%prod.quarkus.flyway.migrate-at-start=false).

Manual schema initialization required: * Execute SQL scripts from data-index-storage-migrations/src/main/resources/db/migration/ * See: PostgreSQL Deployment Guide

See: PostgreSQL Deployment - Database Migrations

Hibernate Configuration

Timezone:

# Use UTC for all timestamp operations
quarkus.hibernate-orm.jdbc.timezone=UTC

Naming strategy:

# Convert camelCase to snake_case for database columns
quarkus.hibernate-orm.physical-naming-strategy=org.hibernate.boot.model.naming.CamelCaseToUnderscoresNamingStrategy

Schema generation:

# Never auto-generate schema (Flyway handles migrations)
quarkus.hibernate-orm.database.generation=none

Logging:

# Log SQL statements (development only)
%dev.quarkus.hibernate-orm.log.sql=true

# Format SQL for readability
%dev.quarkus.hibernate-orm.log.format-sql=true

# Log bind parameters
%dev.quarkus.hibernate-orm.log.bind-parameters=true

Flyway Migrations

Basic configuration:

# Run migrations on startup
quarkus.flyway.migrate-at-start=true

# Migration location
quarkus.flyway.locations=classpath:db/migration

# Baseline version (for existing databases)
quarkus.flyway.baseline-version=1
quarkus.flyway.baseline-on-migrate=false

Production settings:

# Disable in production (use init container or job)
%prod.quarkus.flyway.migrate-at-start=false

# Enable for development
%dev.quarkus.flyway.migrate-at-start=true

GraphQL API Configuration

Endpoint:

# GraphQL endpoint path
quarkus.smallrye-graphql.root-path=/graphql

# Enable GraphiQL UI
quarkus.smallrye-graphql.ui.always-include=true

# GraphiQL UI path (browser)
# http://localhost:8080/graphql

Error handling:

# Print DataFetcher exceptions to logs
quarkus.smallrye-graphql.print-data-fetcher-exception=true

# Log query and variables for debugging
quarkus.smallrye-graphql.log-payload=queryAndVariables

Field visibility:

# Field visibility: DEFAULT, NO_INTROSPECTION, or NO_INTROSPECTION_OR_QUERY
quarkus.smallrye-graphql.field-visibility=DEFAULT

Performance:

# Enable query complexity limits (prevent DoS)
quarkus.smallrye-graphql.enable-get=false

# Maximum query depth
quarkus.smallrye-graphql.max-depth=15

HTTP Server Configuration

Port:

# HTTP port
quarkus.http.port=8080

# HTTPS port (if SSL enabled)
quarkus.http.ssl-port=8443

Compression:

# Enable HTTP compression
quarkus.http.enable-compression=true

CORS (for browser access):

# Enable CORS
quarkus.http.cors=true

# Allowed origins
quarkus.http.cors.origins=http://localhost:3000,https://my-app.com

# Allowed methods
quarkus.http.cors.methods=GET,POST,PUT,DELETE

# Allowed headers
quarkus.http.cors.headers=Content-Type,Authorization

Health Checks

Endpoints:

# Liveness probe: /q/health/live
quarkus.smallrye-health.liveness.enabled=true

# Readiness probe: /q/health/ready
quarkus.smallrye-health.readiness.enabled=true

Custom checks:

Health checks automatically include:

Database connectivity (PostgreSQL ping)
Disk space

Metrics

Prometheus metrics:

# Enable metrics endpoint: /q/metrics
quarkus.micrometer.export.prometheus.enabled=true

# Include JVM metrics
quarkus.micrometer.binder.jvm=true

# Include system metrics
quarkus.micrometer.binder.system=true

# Include HTTP server metrics
quarkus.micrometer.binder.http-server.enabled=true

Logging

Log levels:

# Root log level
quarkus.log.level=INFO

# Data Index service
quarkus.log.category."org.kubesmarts.logic.dataindex".level=DEBUG

# Hibernate SQL (development)
%dev.quarkus.log.category."org.hibernate.SQL".level=DEBUG
%dev.quarkus.log.category."org.hibernate.type.descriptor.sql.BasicBinder".level=TRACE

# GraphQL
quarkus.log.category."io.smallrye.graphql".level=INFO

Log format:

# Console log format
quarkus.log.console.format=%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n

# JSON logging (for log aggregation)
quarkus.log.console.json=false
%prod.quarkus.log.console.json=true

Log file (optional):

# Enable file logging
quarkus.log.file.enable=true

# Log file path
quarkus.log.file.path=/var/log/data-index/data-index.log

# Log file rotation
quarkus.log.file.rotation.max-file-size=10M
quarkus.log.file.rotation.max-backup-index=5

Application Info

Metadata:

# Application name
quarkus.application.name=data-index

# Version (from pom.xml)
quarkus.application.version=${project.version}

Container Image

Build configuration:

# Enable container image build
quarkus.container-image.build=true

# Image name
quarkus.container-image.group=kubesmarts
quarkus.container-image.name=data-index-service
quarkus.container-image.tag=1.0.0

# Use Jib (fast, efficient)
quarkus.container-image.builder=jib

# JVM arguments in container
quarkus.jib.jvm-arguments=-Dquarkus.http.port=8080,-Xms512m,-Xmx1024m

Quarkus Flow Application Configuration

Configuration for applications that emit events to Data Index.

Structured Logging

Enable structured logging:

# Enable structured logging
quarkus.flow.structured-logging.enabled=true

# Events to capture (default: all workflow.* and task.*)
quarkus.flow.structured-logging.events=workflow.*,task.*

# Timestamp format: epoch-seconds (required for Data Index)
quarkus.flow.structured-logging.timestamp-format=epoch-seconds

Console handler:

# Create dedicated console handler for structured logging
quarkus.log.handler.console."FLOW_EVENTS_CONSOLE".enabled=true

# Output format: raw JSON (no formatting)
quarkus.log.handler.console."FLOW_EVENTS_CONSOLE".format=%s%n

# Route structured logging to this handler
quarkus.log.category."io.quarkiverse.flow.structuredlogging".handlers=FLOW_EVENTS_CONSOLE
quarkus.log.category."io.quarkiverse.flow.structuredlogging".use-parent-handlers=false
quarkus.log.category."io.quarkiverse.flow.structuredlogging".level=INFO

The timestamp format MUST be epoch-seconds for Data Index compatibility.

File Handler (Optional)

For debugging:

# File handler for events (development only)
%dev.quarkus.log.handler.file."FLOW_EVENTS_FILE".enabled=true
%dev.quarkus.log.handler.file."FLOW_EVENTS_FILE".path=/tmp/quarkus-flow-events.log
%dev.quarkus.log.handler.file."FLOW_EVENTS_FILE".format=%s%n

# Add to category handlers
%dev.quarkus.log.category."io.quarkiverse.flow.structuredlogging".handlers=FLOW_EVENTS_CONSOLE,FLOW_EVENTS_FILE

File handler should be disabled in Kubernetes. FluentBit tails container stdout, not files.

Kubernetes Deployment

Namespace:

# Deploy to workflows namespace (FluentBit requirement)
quarkus.kubernetes.namespace=workflows

# Or configure FluentBit to watch your namespace

Labels:

# Add labels for FluentBit filtering
quarkus.kubernetes.labels."app"=my-workflow-app
quarkus.kubernetes.labels."version"=1.0.0

Environment-Specific Configuration

Development (`%dev`)

# Local PostgreSQL
%dev.quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/dataindex
%dev.quarkus.datasource.username=postgres
%dev.quarkus.datasource.password=postgres

# Enable Flyway migrations
%dev.quarkus.flyway.migrate-at-start=true

# Enable SQL logging
%dev.quarkus.hibernate-orm.log.sql=true
%dev.quarkus.hibernate-orm.log.format-sql=true

# CORS for local frontend
%dev.quarkus.http.cors=true
%dev.quarkus.http.cors.origins=http://localhost:3000

Testing (`%test`)

# Use test database or H2 in-memory
%test.quarkus.datasource.jdbc.url=jdbc:h2:mem:testdb

# Drop and create schema for each test
%test.quarkus.hibernate-orm.database.generation=drop-and-create

# Run Flyway migrations
%test.quarkus.flyway.migrate-at-start=true
%test.quarkus.flyway.clean-at-start=true

Production (`%prod`)

# Database from environment variables
%prod.quarkus.datasource.jdbc.url=${QUARKUS_DATASOURCE_JDBC_URL}
%prod.quarkus.datasource.username=${QUARKUS_DATASOURCE_USERNAME}
%prod.quarkus.datasource.password=${QUARKUS_DATASOURCE_PASSWORD}

# Disable Flyway (use init container)
%prod.quarkus.flyway.migrate-at-start=false

# JSON logging for log aggregation
%prod.quarkus.log.console.json=true

# No CORS (use API gateway/ingress)
%prod.quarkus.http.cors=false

# Production JVM settings
%prod.quarkus.jib.jvm-arguments=-Xms512m,-Xmx1024m,-XX:+UseG1GC,-XX:MaxGCPauseMillis=200

Configuration Profiles

Activate profiles with:

# Development
mvn quarkus:dev

# Testing
mvn test

# Production build
mvn package -Dquarkus.profile=prod

# Kubernetes deployment (environment variable)
QUARKUS_PROFILE=prod

External Configuration

Kubernetes ConfigMap

Create ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: data-index-config
  namespace: data-index
data:
  application.properties: |
    quarkus.datasource.db-kind=postgresql
    quarkus.smallrye-graphql.root-path=/graphql
    # ... other properties

Mount in Deployment:

volumeMounts:
- name: config
  mountPath: /deployments/config
volumes:
- name: config
  configMap:
    name: data-index-config

Kubernetes Secrets

For sensitive data:

kubectl create secret generic data-index-secrets \
  --from-literal=db-password='your-password' \
  --namespace data-index

Reference in Deployment:

env:
- name: QUARKUS_DATASOURCE_PASSWORD
  valueFrom:
    secretKeyRef:
      name: data-index-secrets
      key: db-password

Complete Example

application.properties for production Data Index:

# Application
quarkus.application.name=data-index

# Database
quarkus.datasource.db-kind=postgresql
quarkus.datasource.jdbc.url=${QUARKUS_DATASOURCE_JDBC_URL}
quarkus.datasource.username=${QUARKUS_DATASOURCE_USERNAME}
quarkus.datasource.password=${QUARKUS_DATASOURCE_PASSWORD}
quarkus.datasource.jdbc.min-size=5
quarkus.datasource.jdbc.max-size=20

# Hibernate
quarkus.hibernate-orm.jdbc.timezone=UTC
quarkus.hibernate-orm.database.generation=none
quarkus.hibernate-orm.physical-naming-strategy=org.hibernate.boot.model.naming.CamelCaseToUnderscoresNamingStrategy

# Flyway (disabled, use init job)
quarkus.flyway.migrate-at-start=false

# GraphQL
quarkus.smallrye-graphql.root-path=/graphql
quarkus.smallrye-graphql.ui.always-include=true
quarkus.smallrye-graphql.print-data-fetcher-exception=true

# HTTP
quarkus.http.port=8080
quarkus.http.enable-compression=true

# Health & Metrics
quarkus.smallrye-health.liveness.enabled=true
quarkus.smallrye-health.readiness.enabled=true
quarkus.micrometer.export.prometheus.enabled=true

# Logging
quarkus.log.level=INFO
quarkus.log.console.json=true
quarkus.log.category."org.kubesmarts.logic.dataindex".level=DEBUG

# Container image
quarkus.container-image.group=kubesmarts
quarkus.container-image.name=data-index-service
quarkus.jib.jvm-arguments=-Dquarkus.http.port=8080,-Xms512m,-Xmx1024m

Next Steps

Local Development - Set up development environment
PostgreSQL Deployment - Production deployment
Troubleshooting - Common configuration issues