Configuration

Aperture is configured via Spring Boot's application.yml. All properties under aperture.* are Aperture-specific. Standard Spring Boot properties (spring.datasource.*, spring.jpa.*, spring.liquibase.*) work as normal.

Database

spring:
  datasource:
    url: ${DB_URL:jdbc:postgresql://localhost:5432/aperture}
    username: ${DB_USER:aperture}
    password: ${DB_PASS:password}
    driver-class-name: org.postgresql.Driver
  jpa:
    open-in-view: false
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQLDialect
  liquibase:
    change-log: classpath:db/changelog/db.changelog-master.xml

Aperture requires PostgreSQL. spring.liquibase.change-log must point to the root changelog generated by the build.

JWT authentication (aperture.auth.jwt)

Property	Type	Default	Description
aperture.auth.jwt.secret	string	—	Required. HMAC signing key. Use ${APERTURE_JWT_SECRET}. Minimum 32 bytes.
aperture.auth.jwt.issuer	string	—	JWT iss claim value
aperture.auth.jwt.audience	string	—	JWT aud claim value
aperture.auth.jwt.access-duration	ISO 8601 duration	PT15M	Access token lifetime
aperture.auth.refresh-duration	ISO 8601 duration	PT720H	Refresh token lifetime (30 days)
aperture.auth.simple.enabled	boolean	true	Set false to disable all simple-auth endpoints (when using a custom CredentialValidator)

Production warning: never use a hardcoded jwt.secret. Always read from an environment variable or secrets manager.

aperture:
  auth:
    jwt:
      secret: ${APERTURE_JWT_SECRET}
      issuer: my-app
      audience: my-api
      access-duration: PT15M
    refresh-duration: PT720H

CORS (aperture.cors)

Property	Type	Default	Description
aperture.cors.enabled	boolean	false	Enable CORS support
aperture.cors.allowed-origins	list of strings	[]	Exact origins (e.g. https://app.example.com)
aperture.cors.allowed-origin-patterns	list of strings	[]	Wildcard patterns (e.g. https://*.example.com)
aperture.cors.max-age	long (seconds)	3600	Preflight cache duration

Note: aperture.cors.enabled=true requires at least one origin or pattern. Aperture will refuse to start if CORS is enabled with no origins configured.

aperture:
  cors:
    enabled: true
    allowed-origins:
      - https://app.example.com

Field encryption (aperture.encryption.local)

Property	Type	Default	Description
aperture.encryption.local.key	string (Base64)	demo key	Must be overridden in production. 32-byte AES-256 key, Base64-encoded.

Generate a key: openssl rand -base64 32

aperture:
  encryption:
    local:
      key: ${APERTURE_ENCRYPTION_KEY}

Hooks (aperture.hooks)

Property	Type	Default	Description
aperture.hooks.secret	string	default-secret	Shared secret sent in X-Hook-Secret header
aperture.hooks.base-url	string	(empty)	Override the host portion of all hook URLs
aperture.hooks.timeout.commit	duration string	5s	Timeout for PRECOMMIT/POSTCOMMIT hooks
aperture.hooks.timeout.async	duration string	5s	Timeout for async hooks and PREENRICH
aperture.hooks.timeout.connect	duration string	2s	TCP connect timeout

aperture:
  hooks:
    secret: ${APERTURE_HOOK_SECRET}
    timeout:
      commit: 10s
      async: 10s
      connect: 3s

MCP (aperture.mcp / spring.ai.mcp)

Property	Type	Default	Description
aperture.mcp.enabled	boolean	false	Enable MCP tool generation and server
spring.ai.mcp.server.protocol	string	STATELESS	MCP transport (stateless HTTP)
spring.ai.mcp.server.name	string	—	MCP server name shown to clients
spring.ai.mcp.server.version	string	—	MCP server version shown to clients

Security (aperture.server)

Property	Type	Default	Description
aperture.server.https-only	boolean	false	Reject HTTP requests and redirect to HTTPS

OpenAPI / Swagger

Aperture includes Springdoc integration. Enable the Swagger UI:

springdoc:
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
  api-docs:
    enabled: true
    path: /v3/api-docs

When enabled, the generated OpenAPI spec includes all entity endpoints, auth and management endpoints, and request/response schemas derived from the manifests.

Bootstrap admin

The superadmin account used during initial setup:

aperture:
  bootstrap:
    admin-password: ${APERTURE_BOOTSTRAP_ADMIN_PASSWORD}

This account has SuperAdmin role and is used to provision the first tenant. Set a strong password and change it after initial setup.

Complete example (application.yml)

spring:
  datasource:
    url: ${DB_URL}
    username: ${DB_USER}
    password: ${DB_PASS}
    driver-class-name: org.postgresql.Driver
  jpa:
    open-in-view: false
  liquibase:
    change-log: classpath:db/changelog/db.changelog-master.xml

aperture:
  cors:
    enabled: true
    allowed-origins:
      - ${FRONTEND_URL}
  auth:
    jwt:
      secret: ${APERTURE_JWT_SECRET}
      issuer: my-app
      audience: my-api
      access-duration: PT15M
    refresh-duration: PT24H
  encryption:
    local:
      key: ${APERTURE_ENCRYPTION_KEY}
  hooks:
    secret: ${APERTURE_HOOK_SECRET}
  bootstrap:
    admin-password: ${APERTURE_BOOTSTRAP_ADMIN_PASSWORD}