Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions content/docs/ai/mcp.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,10 @@ The configuration file must be in the `toml` format. By default, the server look

Each setting can also be overridden using `IGGY_MCP_<SECTION>_<KEY>`, for example `IGGY_MCP_IGGY_USERNAME` or `IGGY_MCP_HTTP_ADDRESS`. Nested settings use the same underscore convention, such as `IGGY_MCP_IGGY_TLS_ENABLED`. Set `IGGY_MCP_ENV_PATH` to load a particular dotenv file; otherwise `.env` is searched for in the current directory and its parents. Existing environment variables take precedence over dotenv values.

Run `iggy-mcp --list-config-env-vars` to print every supported MCP configuration variable and exit before loading dotenv or configuration files or creating the Tokio runtime. The output is sorted and contains names only. If a configuration field is an indexed vector, its template uses `<N>` for indices from `0` through `255`; whole-value vectors are listed once without a placeholder.

`iggy-mcp` rejects unknown command-line arguments with exit code 2. Keep client and container argument lists empty unless they contain a supported flag.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a bit circular. Something like "MCP clients and containers must not pass unknown arguments," and even that may be redundant.

The `token` value can be either a literal PAT or a `file:` reference such as `token = "file:/run/secrets/iggy_pat"`, in which case the token is read from the given file and surrounding whitespace is removed (`~/` is expanded to the home directory). A non-empty token takes precedence over the username and password.

## Available tools
Expand Down
6 changes: 6 additions & 0 deletions content/docs/connectors/runtime.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,12 @@ The [docker image](https://hub.docker.com/r/apache/iggy-connect) is available, a
- On startup the runtime loads environment variables from the first `.env` file found in the working directory or its parents, or from the file pointed to by `IGGY_CONNECTORS_ENV_PATH`.
- Supported scalar fields and indexed list entries can be overridden by environment variables using the `IGGY_CONNECTORS_<SECTION>_<KEY>` convention (nested keys joined by underscores), e.g. `IGGY_CONNECTORS_IGGY_USERNAME` or `IGGY_CONNECTORS_HTTP_ADDRESS`.

Run `iggy-connectors --list-config-env-vars` to print the supported names and templates, then exit before dotenv and configuration loading, runtime creation, plugin loading, or other startup activity. The output is sorted and uses these placeholders:

- `<N>` is a vector index from `0` through `255` for connector stream fields. Whole-value vectors are listed once without a placeholder.
- `<KEY>` is the configured connector key, uppercased. These per-connector overrides are available only with the local configuration provider.
- `<FIELD>` sets one lowercased top-level plugin configuration key. Underscores are preserved (`A_B` becomes `a_b`, not nested `a.b`), and nested plugin configuration keys cannot be set through environment variables. `FORMAT` is reserved and is listed separately as `..._PLUGIN_CONFIG_FORMAT`; the passthrough template does not guarantee that a plugin accepts every field.

## How plugins are resolved

The `path` field of a connector configuration accepts both `plugin.so` and `plugin` - the OS-specific extension (`.so` / `.dylib` / `.dll`) is appended when missing. Absolute paths are checked at the literal location. Relative paths are searched in order:
Expand Down
5 changes: 4 additions & 1 deletion content/docs/server/configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,8 @@ export IGGY_SHARDING_CPU_ALLOCATION=4 # [sharding] cpu_allocation

Two variables live outside the config schema: `IGGY_ROOT_USERNAME` and `IGGY_ROOT_PASSWORD` set the root credentials, always as a pair. They initialize the root user **only at first creation**. On an existing data directory the stored root user is recovered unchanged, but supplied environment credentials must still pass validation.

Run `iggy-server --list-config-env-vars` to print every supported server variable and exit before loading dotenv or configuration files or creating runtime state. The output is sorted, contains names only, and uses `<N>` for indexed vector entries. Most indexed fields accept `0` through `255`; `cluster.nodes.<N>.advertised_addresses.<N>` accepts `0` through `15` for its inner index. Whole-value vector fields are listed once without a placeholder.

### Secrets

Five values are secret-flagged: `http.jwt.encoding_secret`, `http.jwt.decoding_secret`, `encryption.key`, `cluster.auth.shared_secret`, and `cluster.auth.previous_shared_secret`. Prefer setting them through their environment variables (`IGGY_HTTP_JWT_ENCODING_SECRET`, `IGGY_ENCRYPTION_KEY`, `IGGY_CLUSTER_AUTH_SHARED_SECRET`, and so on) instead of storing them in a file. Secret values are masked in logs and **never serialized** into `runtime/current_config.toml`.
Expand All @@ -65,10 +67,11 @@ Five values are secret-flagged: `http.jwt.encoding_secret`, `http.jwt.decoding_s

## Command-line flags

`iggy-server` accepts these three startup options, plus `--help` (`-h`) and `--version` (`-V`):
`iggy-server` accepts these four startup options, plus `--help` (`-h`) and `--version` (`-V`):

| Flag | Description |
|------|-------------|
| `--list-config-env-vars` | Print the supported configuration environment-variable names and templates, then exit without starting the server. See [Environment variables](#environment-variables). |
| `--fresh`, `-f` | Delete the configured data directory (`local_data` by default, see `IGGY_PATH`) before boot and start on empty state. In cluster mode this wipes **this replica only**; it rejoins and refills by state transfer from the others. Wiping a quorum at the same time can destroy committed data. Do not put `--fresh` in a service unit: it would re-transfer the whole dataset on every restart. |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably better if this comes later after the strtup flags

| `--with-default-root-credentials` | Set `IGGY_ROOT_USERNAME` and `IGGY_ROOT_PASSWORD` to `iggy` unless they are already present in the environment. These values initialize the root user only at first creation. Development only. |
| `--replica-id <N>` | Identify this node within `cluster.nodes`. Required when `cluster.enabled = true`; the value must match exactly one `replica_id` in the roster. |
Expand Down