Wanaku Configuration

This document provides a comprehensive overview of the configuration options for all components of the Wanaku project.

Described here are both Wanaku-specific configurations, prefixed with wanaku, and relevant Quarkus-specific configurations, prefixed with quarkus.

NOTE

Quarkus is the ultimate source for their descriptions. In case the description here conflicts with the ones from Quarkus, please consider the ones from them as being the actual correct value.

Properties are typically stored in application.properties files within each module and can be set in runtime using -D<property.name>=<value> or by exporting equivalent environment variables (i.e.: PROPERTY_NAME=<value>).

IMPORTANT

Some of the settings can only be set at build time.

1. Router Backend

Configuration for the main Wanaku Router Backend (wanaku-router-backend), which orchestrates all services.

General & HTTP

Property	Description
`quarkus.http.port`	`8080` - The primary HTTP port for the router backend.
`quarkus.http.cors.enabled`	`true` - Enables Cross-Origin Resource Sharing (CORS).
`quarkus.http.cors.origins`	A comma-separated list of allowed origins for CORS requests (e.g., for the admin UI).
`quarkus.http.access-log.enabled`	`true` - Enables the HTTP access log for monitoring requests.

Multi-Component Protocol (MCP) Server

Property	Description
`quarkus.grpc.server.use-separate-server`	`false` - The gRPC server shares the main HTTP server, avoiding the need for a separate port.
`quarkus.mcp.server.wanaku-internal.sse.root-path`	`/wanaku-internal/mcp` - The SSE endpoint path for the internal MCP namespace.
`quarkus.mcp.server.ns-*.sse.root-path`	`/ns-*/mcp` - The SSE endpoint paths for the 10 available external namespaces (`ns-1` to `ns-10`).
`quarkus.mcp.server.traffic-logging.enabled`	`true` - Enables logging of all MCP traffic for debugging.
`quarkus.mcp.server.traffic-logging.text-limit`	`1000000` - The maximum length of the body to log for MCP traffic.
`quarkus.mcp.server.server-info.name`	`Wanaku` - The name of the server.
`quarkus.mcp.server.server-info.version`	The version of the server, taken from the project version.
`quarkus.mcp.server.client-logging.default-level`	`debug` - The default logging level for MCP clients.

Authentication & Authorization (OIDC)

Property	Description
`auth.server`	The base address of the Keycloak authentication server (e.g., `http://localhost:8543`).
`auth.proxy`	The public-facing address of the OIDC proxy (e.g., `http://localhost:8080`).
`quarkus.oidc.auth-server-url`	The full URL to the Keycloak realm, derived from `auth.server`.
`quarkus.oidc.client-id`	`wanaku-mcp-router` - The OIDC client ID for the router backend itself.
`quarkus.oidc.application-type`	`hybrid` - Allows the backend to act as both a web app (for the admin UI) and a service.
`quarkus.oidc.tls.verification`	`none` - Disables TLS verification for the OIDC provider (for development).
`quarkus.oidc-proxy.enabled`	`true` - Enables the OIDC proxy feature, which simplifies OIDC integration.
`quarkus.http.auth.permission.*.paths`	Defines path patterns for different security policies (`permit`, `authenticated`).
`quarkus.http.auth.permission.*.policy`	Assigns a security policy to the corresponding path pattern.

Persistence (`core-persistence-infinispan`)

Property	Description
`wanaku.persistence.infinispan.base-folder`	Where to store Infinispan files (defaults to `${user.home}/.wanaku/router/`).
`wanaku.infinispan.max-state-count`	`10` - The maximum number of historical states to keep for each service.

2. Capabilities (Tool Services)

Common Capability Settings (`core-capabilities-base`)

These settings apply to most tool services and are foundational for their operation.

Property	Description
`quarkus.http.host-enabled`	`false` - Disables the standard HTTP server for most capabilities, as they use gRPC for communication.
`quarkus.grpc.server.host`	`0.0.0.0` - Binds the gRPC server to all available network interfaces.
`quarkus.grpc.server.port`	A unique port for each capability's gRPC server (e.g., `9009` for `exec`).
`quarkus.qute.strict-rendering`	`false` - Allows for more lenient Qute template rendering.
`wanaku.service.name`	The unique, lowercase name of the service (e.g., `exec`, `http`).
`wanaku.service.base-uri`	The base URI scheme for tools provided by this service (e.g., `exec://`).
`quarkus.oidc-client.auth-server-url`	The URL of the Keycloak realm for authentication.
`quarkus.oidc-client.client-id`	`wanaku-service` - The shared OIDC client ID for all capabilities.
`quarkus.oidc-client.credentials.secret`	The OIDC client secret for the capability. Must be replaced with a real secret.

Common Service Registration Settings

These wanaku.service.registration.* properties are available for all capabilities to manage their discovery and lifecycle.

Property	Description
`wanaku.service.registration.enabled`	`true` - Enables the service registration feature. Found in archetypes.
`wanaku.service.registration.uri`	The URI of the router backend for registration (e.g., `http://localhost:8080`).
`wanaku.service.registration.interval`	`10s` - The interval at which the service should ping the router to show it's alive.
`wanaku.service.registration.retries`	`3` - Number of times to retry a failed registration.
`wanaku.service.registration.retry-wait-seconds`	`1` - Seconds to wait before retrying a failed registration.
`wanaku.service.registration.delay-seconds`	`3` - Seconds to delay the initial registration after startup.
`wanaku.service.registration.announce-address`	A custom address to announce to the router, overriding the auto-detected one.

Secret Encryption

Secrets can be encrypted at rest using AES-256. Set both environment variables to enable:

Environment Variable	Description
`WANAKU_SECRETS_ENCRYPTION_PASSWORD`	Password for key derivation
`WANAKU_SECRETS_ENCRYPTION_SALT`	Salt for key derivation

When both are set, secrets are automatically encrypted when written and decrypted when read.

3. CLI

Configuration for the Wanaku command-line interface (wanaku-cli).

Property	Description
`wanaku.cli.tool.create-cmd`	The full Maven command to execute when creating a new tool service via `wanaku tool create`.
`wanaku.cli.resource.create-cmd`	The full Maven command to execute when creating a new resource provider via `wanaku resource create`.
`wanaku.cli.mcp.create-cmd`	The full Maven command to execute when creating a new MCP server via `wanaku mcp create`.
`wanaku.cli.components.*`	URL templates for downloading various Wanaku components. `%s` is replaced with the version number.
`wanaku.cli.default-services`	A comma-separated list of default services to start automatically when running the router.

4. Archetypes

These properties are found in the project archetypes and serve as templates for new services.

`wanaku-mcp-servers-archetype`

Property	Description
`wanaku.mcp.service.name`	The name of the new MCP service, typically derived from the `name` variable.
`wanaku.mcp.service.namespace`	The namespace the MCP service will operate on.
`wanaku.service.registration.mcp-forward-address`	The address to forward MCP messages to.

`wanaku-provider-archetype` & `wanaku-tool-service-archetype`

Property	Description
`wanaku.service.service.configurations.*`	A way to define user-exposable configurations for a service. The key becomes the configuration name.
`wanaku.service.service.defaults.*`	Defines default values for the corresponding `configurations`.

5. Testing

Properties primarily used when running tests.

Property	Description
`keycloak.docker.image`	Overrides the default Keycloak Docker image used for tests. This is set via a system property in the `pom.xml`, not in `application.properties`.
`%test.quarkus.log.file.enable`	`true` - Enables logging to a file during tests.
`%test.quarkus.log.file.path`	`target/wanaku.log` - The path to the log file for test runs.

Global Concepts

Quarkus Profiles

Quarkus uses profiles to manage environment-specific configurations. You will see properties prefixed with %dev, %test, or other custom profiles. These properties are only active when that profile is enabled.

%dev: Used when running in development mode (quarkus dev).
%test: Used when running automated tests.
%prod: Used for production deployments (default when no profile is specified).

Environment Variables

Most properties can be set via environment variables by converting the property name:

Convert to uppercase
Replace dots (.) with underscores (_)
Replace hyphens (-) with underscores (_)

Example:

properties

quarkus.http.port=8080

Becomes:

shell

QUARKUS_HTTP_PORT=8080

Configuration Examples

Example: Router Backend with Custom OIDC

properties

# application.properties for router backend
quarkus.http.port=8080
quarkus.http.cors.enabled=true
quarkus.http.cors.origins=http://localhost:3000,https://my-frontend.example.com

auth.server=https://keycloak.example.com
auth.proxy=https://wanaku.example.com

quarkus.oidc.client-id=wanaku-mcp-router
quarkus.oidc.application-type=hybrid
quarkus.oidc.tls.verification=required

wanaku.persistence.infinispan.base-folder=/var/lib/wanaku/data
wanaku.infinispan.max-state-count=20

Example: Tool Service with Custom Registration

properties

# application.properties for a tool service
quarkus.http.host-enabled=false
quarkus.grpc.server.host=0.0.0.0
quarkus.grpc.server.port=9010

wanaku.service.name=my-custom-tool
wanaku.service.base-uri=custom://

wanaku.service.registration.enabled=true
wanaku.service.registration.uri=http://wanaku-router:8080
wanaku.service.registration.interval=15s
wanaku.service.registration.announce-address=my-custom-tool.example.com:9010

quarkus.oidc-client.auth-server-url=https://keycloak.example.com/realms/wanaku
quarkus.oidc-client.client-id=wanaku-service
quarkus.oidc-client.credentials.secret=${WANAKU_SERVICE_SECRET}

Example: CLI Configuration

properties

# ~/.wanaku/cli.properties
wanaku.cli.default-services=http,exec,tavily

Example: Enabling Secret Encryption

shell

export WANAKU_SECRETS_ENCRYPTION_PASSWORD="your-strong-password"
export WANAKU_SECRETS_ENCRYPTION_SALT="unique-salt-value"

Additional Resources

Quarkus Configuration Guide - Comprehensive Quarkus configuration documentation
Keycloak Documentation - OIDC and authentication setup
Infinispan Configuration - Persistence layer configuration

Wanaku Configuration ​

1. Router Backend ​

General & HTTP ​

Multi-Component Protocol (MCP) Server ​

Authentication & Authorization (OIDC) ​

Persistence (core-persistence-infinispan) ​

2. Capabilities (Tool Services) ​

Common Capability Settings (core-capabilities-base) ​

Common Service Registration Settings ​

Secret Encryption ​

3. CLI ​

4. Archetypes ​

wanaku-mcp-servers-archetype ​

wanaku-provider-archetype & wanaku-tool-service-archetype ​

5. Testing ​

Global Concepts ​

Quarkus Profiles ​

Environment Variables ​

Configuration Examples ​

Example: Router Backend with Custom OIDC ​

Example: Tool Service with Custom Registration ​

Example: CLI Configuration ​

Example: Enabling Secret Encryption ​

Additional Resources ​

Wanaku Configuration

1. Router Backend

General & HTTP

Multi-Component Protocol (MCP) Server

Authentication & Authorization (OIDC)

Persistence (`core-persistence-infinispan`)

2. Capabilities (Tool Services)

Common Capability Settings (`core-capabilities-base`)

Common Service Registration Settings

Secret Encryption

3. CLI

4. Archetypes

`wanaku-mcp-servers-archetype`

`wanaku-provider-archetype` & `wanaku-tool-service-archetype`

5. Testing

Global Concepts

Quarkus Profiles

Environment Variables

Configuration Examples

Example: Router Backend with Custom OIDC

Example: Tool Service with Custom Registration

Example: CLI Configuration

Example: Enabling Secret Encryption

Additional Resources