This is an automated email from the ASF dual-hosted git repository.
hubcio pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iggy-website.git
The following commit(s) were added to refs/heads/main by this push:
new 3ebe50e1 chore(docs): provide detail for new configuration (#68)
3ebe50e1 is described below
commit 3ebe50e127adcaef8668e9e76251ae38606b67b4
Author: Chengxi Luo <[email protected]>
AuthorDate: Thu Sep 3 03:23:25 2026 -0400
chore(docs): provide detail for new configuration (#68)
---
content/docs/introduction/getting-started.mdx | 3 ++-
content/docs/sdk/node/examples.mdx | 1 +
content/docs/sdk/node/intro.mdx | 1 +
content/docs/sdk/php/intro.mdx | 1 +
content/docs/sdk/python/examples.mdx | 1 +
content/docs/sdk/python/intro.mdx | 1 +
content/docs/server/configuration.mdx | 14 ++++++++++++++
content/docs/server/docker.mdx | 12 ++++++++++--
content/docs/web_ui/start.mdx | 3 +++
src/components/architecture-diagrams.tsx | 2 +-
10 files changed, 35 insertions(+), 4 deletions(-)
diff --git a/content/docs/introduction/getting-started.mdx
b/content/docs/introduction/getting-started.mdx
index 2547616b..97ba8c9e 100644
--- a/content/docs/introduction/getting-started.mdx
+++ b/content/docs/introduction/getting-started.mdx
@@ -28,11 +28,12 @@ docker run --rm \
--cap-add=SYS_NICE --security-opt seccomp=unconfined --ulimit memlock=-1:-1 \
-p 8090:8090 \
-e IGGY_TCP_ADDRESS=0.0.0.0:8090 \
+ -e IGGY_NODE_ADVERTISED_ADDRESS=localhost \
-e IGGY_ROOT_USERNAME=iggy -e IGGY_ROOT_PASSWORD=iggy \
apache/iggy:latest
```
-`SYS_NICE`, the seccomp setting and the memlock limit are all required by
`io_uring` and the thread-per-core architecture; see [Docker &
Helm](/docs/server/docker) for the details. `IGGY_TCP_ADDRESS` is needed
because the server binds to `127.0.0.1` inside the container by default, which
a published port cannot reach. Setting the root credentials explicitly means
the username and password used later in this guide will work.
+`SYS_NICE`, the seccomp setting and the memlock limit are all required by
`io_uring` and the thread-per-core architecture; see [Docker &
Helm](/docs/server/docker) for the details. `IGGY_TCP_ADDRESS` is needed
because the server binds to `127.0.0.1` inside the container by default, which
a published port cannot reach. `IGGY_NODE_ADVERTISED_ADDRESS` is needed because
that wildcard leaves the server with no address to give clients, and it refuses
to start rather than publish one nobody can [...]
Alternatively, build from source by cloning the
[repository](https://github.com/apache/iggy) and running:
diff --git a/content/docs/sdk/node/examples.mdx
b/content/docs/sdk/node/examples.mdx
index fb5accd4..caae3e0c 100644
--- a/content/docs/sdk/node/examples.mdx
+++ b/content/docs/sdk/node/examples.mdx
@@ -24,6 +24,7 @@ docker run --rm \
--cap-add=SYS_NICE --security-opt seccomp=unconfined --ulimit memlock=-1:-1 \
-p 8090:8090 \
-e IGGY_TCP_ADDRESS=0.0.0.0:8090 \
+ -e IGGY_NODE_ADVERTISED_ADDRESS=localhost \
-e IGGY_ROOT_USERNAME=iggy -e IGGY_ROOT_PASSWORD=iggy \
apache/iggy:latest
diff --git a/content/docs/sdk/node/intro.mdx b/content/docs/sdk/node/intro.mdx
index 359dd623..62573825 100644
--- a/content/docs/sdk/node/intro.mdx
+++ b/content/docs/sdk/node/intro.mdx
@@ -23,6 +23,7 @@ docker run --rm \
--cap-add=SYS_NICE --security-opt seccomp=unconfined --ulimit memlock=-1:-1 \
-p 8090:8090 \
-e IGGY_TCP_ADDRESS=0.0.0.0:8090 \
+ -e IGGY_NODE_ADVERTISED_ADDRESS=localhost \
-e IGGY_ROOT_USERNAME=iggy -e IGGY_ROOT_PASSWORD=iggy \
apache/iggy:latest
diff --git a/content/docs/sdk/php/intro.mdx b/content/docs/sdk/php/intro.mdx
index aa3e120b..d29c1087 100644
--- a/content/docs/sdk/php/intro.mdx
+++ b/content/docs/sdk/php/intro.mdx
@@ -42,6 +42,7 @@ docker run --rm \
--cap-add=SYS_NICE --security-opt seccomp=unconfined --ulimit memlock=-1:-1 \
-p 8090:8090 \
-e IGGY_TCP_ADDRESS=0.0.0.0:8090 \
+ -e IGGY_NODE_ADVERTISED_ADDRESS=localhost \
-e IGGY_ROOT_USERNAME=iggy -e IGGY_ROOT_PASSWORD=iggy \
apache/iggy:latest
diff --git a/content/docs/sdk/python/examples.mdx
b/content/docs/sdk/python/examples.mdx
index d0fa72d8..9bf7c115 100644
--- a/content/docs/sdk/python/examples.mdx
+++ b/content/docs/sdk/python/examples.mdx
@@ -19,6 +19,7 @@ docker run --rm \
--cap-add=SYS_NICE --security-opt seccomp=unconfined --ulimit memlock=-1:-1 \
-p 8090:8090 \
-e IGGY_TCP_ADDRESS=0.0.0.0:8090 \
+ -e IGGY_NODE_ADVERTISED_ADDRESS=localhost \
-e IGGY_ROOT_USERNAME=iggy -e IGGY_ROOT_PASSWORD=iggy \
apache/iggy:latest
diff --git a/content/docs/sdk/python/intro.mdx
b/content/docs/sdk/python/intro.mdx
index a777c689..d114ef2e 100644
--- a/content/docs/sdk/python/intro.mdx
+++ b/content/docs/sdk/python/intro.mdx
@@ -23,6 +23,7 @@ docker run --rm \
--cap-add=SYS_NICE --security-opt seccomp=unconfined --ulimit memlock=-1:-1 \
-p 8090:8090 \
-e IGGY_TCP_ADDRESS=0.0.0.0:8090 \
+ -e IGGY_NODE_ADVERTISED_ADDRESS=localhost \
-e IGGY_ROOT_USERNAME=iggy -e IGGY_ROOT_PASSWORD=iggy \
apache/iggy:latest
diff --git a/content/docs/server/configuration.mdx
b/content/docs/server/configuration.mdx
index 1f0c4f49..8a863186 100644
--- a/content/docs/server/configuration.mdx
+++ b/content/docs/server/configuration.mdx
@@ -11,6 +11,9 @@ A config file doesn't have to be complete. It is **merged
over the embedded defa
[system]
path = "/var/lib/iggy"
+[node]
+advertised_address = "iggy-1"
+
[tcp]
address = "0.0.0.0:8090"
@@ -18,6 +21,8 @@ address = "0.0.0.0:8090"
address = "0.0.0.0:3000"
```
+Both listeners here bind a wildcard, which tells the server nothing about
where clients reach it, so [`[node]`](#node) has to name that address
explicitly - without it this file is refused at boot.
+
## How configuration loads
Configuration is resolved in three layers. Later layers win:
@@ -36,6 +41,7 @@ Every configuration key can be overridden with an `IGGY_`
variable. The name is
```bash
IGGY_TCP_ADDRESS=0.0.0.0:8090 # [tcp] address
+IGGY_NODE_ADVERTISED_ADDRESS=iggy-1 # [node] advertised_address
IGGY_HTTP_ENABLED=true # [http] enabled
IGGY_SYSTEM_PATH=/var/lib/iggy # [system] path
IGGY_SYSTEM_LOGGING_LEVEL=debug # [system.logging] level
@@ -411,6 +417,14 @@ Tunables for the internal bus that ships consensus traffic
between replicas and
|-----|---------|-------------|
| `rebalancing_timeout` | `"30s"` | Maximum time a partition can remain in
pending revocation before being force-transferred to the target member. |
+### `[node]`
+
+This node's own client-facing identity. The address is read only while
`cluster.enabled = false`: in cluster mode the roster answers the same question
per node, so the address itself is ignored and the server says so at startup.
The key is still validated in every mode, so a malformed value refuses boot
even with `cluster.enabled = true`.
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `advertised_address` | unset | The address clients dial, published in
cluster metadata. A literal IP or a DNS hostname. Left unset, the server
derives it from the bind address of the first enabled listener; that fails when
the listener binds a wildcard, and the server refuses to start rather than
publish an address no client can use. Declaring the unspecified address
(`0.0.0.0`, `::`) is refused for the same reason. |
+
### `[cluster]`
Cluster mode is configured here but documented in
[Clustering](/docs/clustering/vsr). The section contains:
diff --git a/content/docs/server/docker.mdx b/content/docs/server/docker.mdx
index 339b3cb0..d4df55bb 100644
--- a/content/docs/server/docker.mdx
+++ b/content/docs/server/docker.mdx
@@ -11,6 +11,7 @@ Two properties of the published image matter for any
deployment:
- The working directory is `/app` and the `iggy-server` and `iggy` binaries
are on `PATH` (`/usr/local/bin`). The default data directory `local_data`
therefore resolves to `/app/local_data` - **mount your volume there**, or set
`IGGY_SYSTEM_PATH` and mount that path instead.
- The image bakes in no address overrides, so the server binds the loopback
defaults (`127.0.0.1`) and is **unreachable from outside the container** even
with published ports. Set `IGGY_TCP_ADDRESS=0.0.0.0:8090` (and the equivalent
for every other transport you expose) alongside the `-p` flags.
+- The wildcard says nothing about where clients reach the container, so the
server refuses to start until `IGGY_NODE_ADVERTISED_ADDRESS` supplies that
address. Use `localhost` when the ports are published to the host, the compose
service name when the clients are containers on the same network, and the
external hostname or load balancer name when they are further away. The value
reaches clients through cluster metadata, where it is the endpoint they
reconnect through.
Below is an example `docker-compose.yml` which overrides the default
configuration (see [Configuration](/docs/server/configuration)) with
environment variables. If you prefer using the configuration file, you can
mount it as a volume and provide the path to it with the `IGGY_CONFIG_PATH`
environment variable.
@@ -35,6 +36,7 @@ services:
- IGGY_ROOT_PASSWORD=Secret123
- IGGY_TCP_ADDRESS=0.0.0.0:8090
- IGGY_HTTP_ADDRESS=0.0.0.0:3000
+ - IGGY_NODE_ADVERTISED_ADDRESS=localhost
- IGGY_QUIC_ENABLED=false
- IGGY_WEBSOCKET_ENABLED=false
ports:
@@ -54,6 +56,7 @@ docker run -d --name iggy \
--cap-add=SYS_NICE --security-opt seccomp=unconfined --ulimit memlock=-1:-1 \
-e IGGY_ROOT_USERNAME=iggy -e IGGY_ROOT_PASSWORD=Secret123 \
-e IGGY_TCP_ADDRESS=0.0.0.0:8090 -e IGGY_HTTP_ADDRESS=0.0.0.0:3000 \
+ -e IGGY_NODE_ADVERTISED_ADDRESS=localhost \
-p 8090:8090 -p 3000:3000 \
-v iggy:/app/local_data \
apache/iggy:latest
@@ -85,7 +88,7 @@ The repository root carries its own `Dockerfile` and
`docker-compose.yml` for bu
docker build -t iggy .
```
-Or use `docker compose up` directly from the repository root. That image
**differs from the published one**: it sets the `0.0.0.0` listener addresses
via `ENV` and keeps its data at `/local_data`.
+Or use `docker compose up` directly from the repository root. That image
**differs from the published one**: it sets the `0.0.0.0` address of all four
listeners via `ENV` and keeps its data at `/local_data`. Those wildcards are
baked into the image, so a plain `docker run` of it refuses to start until you
pass `IGGY_NODE_ADVERTISED_ADDRESS` yourself. The repository's compose file
publishes the ports to the host, so it declares
`IGGY_NODE_ADVERTISED_ADDRESS=localhost`.
### Running the CLI inside the container
@@ -107,7 +110,7 @@ helm install iggy ./helm/charts/iggy
### Chart components
-- **Server Deployment** - runs `apache/iggy` with the pod security context the
server needs: seccomp profile `Unconfined` (for `io_uring`) plus the `IPC_LOCK`
capability (for memory locking). Listener addresses are set to `0.0.0.0` via
`server.env`, and the data volume mounts at `/app/local_data`.
+- **Server Deployment** - runs `apache/iggy` with the pod security context the
server needs: seccomp profile `Unconfined` (for `io_uring`) plus the `IPC_LOCK`
capability (for memory locking). Listener addresses are set to `0.0.0.0` via
`server.env`, and the data volume mounts at `/app/local_data`. The chart
supplies `IGGY_NODE_ADVERTISED_ADDRESS` as the in-cluster Service DNS name;
override it with `server.advertisedAddress` when clients arrive through a
LoadBalancer or an Ingress. Image [...]
- **Server Service** - exposes the `http` (3000), `quic` (8080), and `tcp`
(8090) ports. WebSocket is not exposed by the chart.
- **Web UI Deployment + Service** - a separate `apache/iggy-web-ui` deployment
on port 3050, enabled by default (`ui.enabled`).
- **Secret** - root user credentials from `server.users.root` (default
`iggy`/`changeit`). Point `existingSecret` at your own Secret in production.
@@ -121,6 +124,11 @@ helm install iggy ./helm/charts/iggy
# values.yaml (excerpt, chart defaults)
server:
replicaCount: 1
+ # The address clients dial, published in cluster metadata. Declaring
+ # IGGY_NODE_ADVERTISED_ADDRESS in server.env instead also works, but
+ # setting both is refused at render time. Empty falls back to the
+ # in-cluster Service DNS name.
+ advertisedAddress: ""
image:
repository: apache/iggy
tag: "0.7.0"
diff --git a/content/docs/web_ui/start.mdx b/content/docs/web_ui/start.mdx
index 2eac8f29..e1ebd9f9 100644
--- a/content/docs/web_ui/start.mdx
+++ b/content/docs/web_ui/start.mdx
@@ -95,6 +95,9 @@ services:
- IGGY_HTTP_ADDRESS=0.0.0.0:80
- IGGY_TCP_ENABLED=true
- IGGY_TCP_ADDRESS=0.0.0.0:3000
+ # The init container below reaches this service by its compose name,
+ # so publish that name rather than localhost.
+ - IGGY_NODE_ADVERTISED_ADDRESS=iggy
- IGGY_QUIC_ENABLED=false
- IGGY_WEBSOCKET_ENABLED=false
ports:
diff --git a/src/components/architecture-diagrams.tsx
b/src/components/architecture-diagrams.tsx
index 99e02330..b6c8cbfe 100644
--- a/src/components/architecture-diagrams.tsx
+++ b/src/components/architecture-diagrams.tsx
@@ -1070,7 +1070,7 @@ export function WhyIggy() {
export function QuickStartSnippet() {
const steps = [
- { n: "1", label: "Start the server", code: "docker run --cap-add=SYS_NICE
--security-opt seccomp=unconfined --ulimit memlock=-1:-1 -p 8090:8090 -e
IGGY_TCP_ADDRESS=0.0.0.0:8090 -e IGGY_ROOT_USERNAME=iggy -e
IGGY_ROOT_PASSWORD=iggy apache/iggy" },
+ { n: "1", label: "Start the server", code: "docker run --cap-add=SYS_NICE
--security-opt seccomp=unconfined --ulimit memlock=-1:-1 -p 8090:8090 -e
IGGY_TCP_ADDRESS=0.0.0.0:8090 -e IGGY_NODE_ADVERTISED_ADDRESS=localhost -e
IGGY_ROOT_USERNAME=iggy -e IGGY_ROOT_PASSWORD=iggy apache/iggy" },
{ n: "2", label: "Add the SDK", code: "cargo add iggy" },
{ n: "3", label: "Connect and send", code: 'let client =
IggyClient::from_connection_string("iggy://iggy:iggy@localhost:8090")?;\nclient.connect().await?;'
},
];
