# 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](https://quarkus.io/guides/all-config) 
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.

## Configuration Basics

Wanaku is built on [Quarkus](https://quarkus.io/), a Java framework that uses `application.properties` files for
configuration. If you are unfamiliar with Quarkus, this section explains how configuration works.

### What is `application.properties`?

`application.properties` is a plain text file containing key-value pairs, one per line. Each line sets a configuration
property:

```properties
quarkus.http.port=8080
wanaku.service.name=my-tool
quarkus.log.level=INFO
```

Lines starting with `#` are comments. Blank lines are ignored.

### Where is `application.properties` located?

Each Wanaku component ships with a built-in `application.properties` file inside its JAR/binary at
`src/main/resources/application.properties`. These files contain sensible defaults and are embedded at build time.

For the main components:

- **Router Backend**: `apps/wanaku-router-backend/src/main/resources/application.properties`
- **Tool Services**: `capabilities/tools/<service>/src/main/resources/application.properties`
- **CLI**: `apps/wanaku-cli/src/main/resources/application.properties`

### How to override configuration at runtime

You do **not** need to modify the built-in files. Quarkus provides several ways to override configuration values when
running Wanaku:

#### 1. External `application.properties` file

Place an `application.properties` file in a `config/` directory next to the Wanaku binary. Quarkus automatically reads
it and any properties defined there override the built-in defaults:

```
my-deployment/
├── wanaku-router-backend-runner.jar
└── config/
    └── application.properties    ← your overrides go here
```

You only need to include the properties you want to change, not the entire file.

#### 2. System properties (`-D` flags)

Pass individual properties on the command line using `-D`:

```shell
java -Dquarkus.http.port=9090 -jar wanaku-router-backend-runner.jar
```

#### 3. Environment variables

Export properties as environment variables. Convert the property name to uppercase, replacing dots (`.`) and hyphens
(`-`) with underscores (`_`):

```shell
export QUARKUS_HTTP_PORT=9090
java -jar wanaku-router-backend-runner.jar
```

#### Priority order

When the same property is defined in multiple places, the following priority applies (highest to lowest):

1. System properties (`-D`)
2. Environment variables
3. External `config/application.properties`
4. Built-in `application.properties` (inside the JAR)

For complete details, see the [Quarkus Configuration Guide](https://quarkus.io/guides/config).

## 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. Both router and capabilities use this mode by default. |
| `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 |
|-----------------------------------------|------------------------------------------------------------------------------------------|
| `wanaku.http.auth` | `keycloak` - Controls authentication mode. Set to `none` to disable authentication entirely. Also settable via `WANAKU_HTTP_AUTH` environment variable. |
| `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. |

#### Running Without Authentication

Set `wanaku.http.auth=none` (or export `WANAKU_HTTP_AUTH=none`) to run without Keycloak.
No identity provider is required — all HTTP paths are opened via `policy=permit` automatically.

```shell
# Via environment variable (recommended for containers / wanaku start local)
WANAKU_HTTP_AUTH=none java -jar quarkus-run.jar

# Via system property
java -Dwanaku.http.auth=none -jar quarkus-run.jar
```

> [!IMPORTANT]
> `wanaku.http.auth` is a **Wanaku-native** property. Users do not need to know that Wanaku is
> built on Quarkus to configure authentication — the Quarkus implementation details stay hidden.

> [!NOTE]
> **How it works internally (`AuthConfigSource`):** When `wanaku.http.auth=none`, a custom
> MicroProfile `ConfigSource` (ordinal 260) injects the following runtime overrides:
>
> | Property injected | Value | Reason |
> |---|---|---|
> | `quarkus.oidc.enabled` | `false` | Disables OIDC entirely at runtime |
> | `quarkus.oidc.discovery-enabled` | `false` | Prevents eager Keycloak connection at startup |
> | `quarkus.oidc.mcp.discovery-enabled` | `false` | Same, for the MCP OIDC tenant used by OidcProxy |
> | `quarkus.oidc.ns-{1..10}.discovery-enabled` | `false` | Same, for per-namespace OIDC tenants |
> | `quarkus.oidc-proxy.enabled` | `false` | Disables the OIDC proxy |
> | `quarkus.http.auth.permission.authenticated.policy` | `permit` | Opens management / data-store APIs |
> | `quarkus.http.auth.permission.mcp-authenticated.policy` | `permit` | Opens MCP namespace endpoints |
> | `quarkus.http.auth.permission.web.policy` | `permit` | Opens the admin web UI |

See the [Usage Guide](usage.md#running-without-authentication) for end-to-end instructions.

### Health Check

These `wanaku.router.health-check.*` properties control the periodic health probing of registered capabilities.

| Property                                      | Description                                                                |
|-----------------------------------------------|----------------------------------------------------------------------------|
| `wanaku.router.health-check.enabled`          | `true` - Enables periodic health checks of registered capability services. |
| `wanaku.router.health-check.interval-seconds` | `60` - The interval in seconds between health check sweeps.                |
| `wanaku.router.health-check.max-concurrent`   | `10` - The maximum number of concurrent health check probes.               |

### gRPC Transport

| Property                                        | Description                                                                                                                           |
|-------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
| `wanaku.bridge.grpc.transport.deadline-seconds` | `10` - The deadline in seconds for gRPC transport calls to capability services. Requests that exceed this deadline will be cancelled. |

### 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.      |

### Namespaces

| Property                                 | Description                                                                                                                                                                                                                                     |
|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `wanaku.router.namespace-age-hard-limit` | `100000000000` - Threshold used to distinguish epoch-seconds from epoch-milliseconds when parsing namespace age timestamps. Values above this limit are interpreted as epoch-milliseconds; values at or below are interpreted as epoch-seconds. |

## 2. Capabilities (Tool Services)

### Common Capability Settings (`wanaku-capabilities-base`)

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

#### Common Settings (All Modes)

These settings apply regardless of whether you use the shared HTTP listener or a separate gRPC server:

| Property | Description |
|------------------------------------------|--------------------------------------------------------------------------------------------------------|
| `wanaku.http.auth` | `keycloak` - Controls authentication mode for capability services. Set to `none` to disable OIDC client. Also settable via `WANAKU_HTTP_AUTH` environment variable. |
| `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://`). |
| `wanaku.service.exec.allowed-executables` | Comma-separated absolute executable paths that the Exec tool may run. |
| `quarkus.qute.strict-rendering` | `false` - Allows for more lenient Qute template rendering. |
| `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.** |

#### Shared HTTP Listener (Recommended)

By default, capabilities are configured to share the HTTP listener with gRPC, avoiding the need for a separate gRPC server port. This simplifies deployment and configuration.

| Property | Description |
|------------------------------------------|--------------------------------------------------------------------------------------------------------|
| `quarkus.http.host-enabled` | `true` - Enables the HTTP server for capabilities (required when using shared listener). |
| `quarkus.http.port` | The HTTP port for the capability (e.g., `9000` for `http` service). |
| `quarkus.http.host` | `0.0.0.0` - Binds the HTTP server to all available network interfaces. |
| `quarkus.grpc.server.use-separate-server` | `false` - The gRPC server shares the HTTP listener (recommended for simpler deployment). |

**Note:** When `use-separate-server=false`, the `quarkus.grpc.server.port` property is ignored because gRPC uses the HTTP port.

#### Separate gRPC Server (Optional)

If you prefer to use a separate gRPC server, set `quarkus.grpc.server.use-separate-server=true` and configure the gRPC-specific properties:

| Property | Description |
|------------------------------------------|--------------------------------------------------------------------------------------------------------|
| `quarkus.http.host-enabled` | `false` - Disables the standard HTTP server (not needed with separate gRPC). |
| `quarkus.grpc.server.use-separate-server` | `true` - Uses a separate gRPC server with its own port. |
| `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`). |

### 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:

1. Convert to uppercase
2. Replace dots (`.`) with underscores (`_`)
3. Replace hyphens (`-`) with underscores (`_`)

**Example:**

```properties
quarkus.http.port=8080
```

Becomes:

```shell
QUARKUS_HTTP_PORT=8080
```

## Configuration Examples

### Example: Router Backend Without Authentication (No Keycloak)

The quickest way to run Wanaku locally without setting up an identity provider:

```shell
# Environment variable — no changes to any properties file needed
export WANAKU_HTTP_AUTH=none
java -jar quarkus-run.jar
```

Or equivalently via a `config/application.properties` override file:

```properties
wanaku.http.auth=none
```

This automatically opens all protected endpoints (`/api/v1/management/*`, `/mcp/*`, `/admin/*`, etc.)
without requiring a token, while OIDC infrastructure stays initialized (preventing startup errors from
the embedded OIDC proxy extension).

### 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 Shared HTTP Listener (Recommended)

```properties
# application.properties for a tool service using shared HTTP listener
quarkus.http.host-enabled=true
quarkus.http.port=9010
quarkus.http.host=0.0.0.0

# gRPC shares the HTTP listener - no separate port needed
quarkus.grpc.server.use-separate-server=false

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}
```

> The realm name defaults to `wanaku` and can be configured via the `AUTH_REALM` environment variable or the `auth.realm` property.

### Example: Tool Service with Separate gRPC Server

```properties
# application.properties for a tool service using separate gRPC server
quarkus.http.host-enabled=false

quarkus.grpc.server.use-separate-server=true
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](https://quarkus.io/guides/config) - Comprehensive Quarkus configuration documentation
- [Keycloak Documentation](https://www.keycloak.org/documentation) - OIDC and authentication setup
- [Infinispan Configuration](https://infinispan.org/docs/stable/titles/configuring/configuring.html) - Persistence layer configuration
