This is an automated email from the ASF dual-hosted git repository.
piotr pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/iggy.git
The following commit(s) were added to refs/heads/master by this push:
new 4277d693 chore(docs): extend iggy-server --help command and update
documentation (#1940)
4277d693 is described below
commit 4277d693c825823605acf97807b6e07b7b825ac9
Author: JarekDev <[email protected]>
AuthorDate: Mon Jun 30 19:52:00 2025 +0200
chore(docs): extend iggy-server --help command and update documentation
(#1940)
- Enhanced iggy-server help command with comprehensive information:
- Added project description, repository links, and website
- Included configuration examples (TOML file and environment variables)
- Added transport protocols overview (TCP, QUIC, HTTP)
- Provided getting started guide with sample commands
- Improved argument descriptions with detailed examples
- Updated main README.md:
- Added reference to --help command for configuration options
- Included environment variable configuration examples
- Enhanced server startup documentation
- Updated examples/rust/README.md:
- Added help command reference for server configuration
- Included environment variable customization examples
Closes #475
---
README.md | 15 ++++++++++
core/server/src/args.rs | 73 ++++++++++++++++++++++++++++++++++++++++++++-----
examples/rust/README.md | 13 +++++++++
3 files changed, 94 insertions(+), 7 deletions(-)
diff --git a/README.md b/README.md
index 9b3d72a2..9b9ec935 100644
--- a/README.md
+++ b/README.md
@@ -171,6 +171,21 @@ Start the server:
`cargo run --bin iggy-server`
+For configuration options and detailed help:
+
+`cargo run --bin iggy-server -- --help`
+
+You can also use environment variables to override any configuration setting:
+
+- Override TCP address
+ `IGGY_TCP_ADDRESS=0.0.0.0:8090 cargo run --bin iggy-server`
+
+- Set custom data path
+ `IGGY_SYSTEM_PATH=/data/iggy cargo run --bin iggy-server`
+
+- Enable HTTP transport
+ `IGGY_HTTP_ENABLED=true cargo run --bin iggy-server`
+
To quickly generate the sample data:
`cargo run --bin data-seeder-tool`
diff --git a/core/server/src/args.rs b/core/server/src/args.rs
index 01136bd7..53236345 100644
--- a/core/server/src/args.rs
+++ b/core/server/src/args.rs
@@ -19,15 +19,74 @@
use clap::Parser;
#[derive(Parser, Debug)]
-#[command(author, version, about, long_about = None)]
+#[command(
+ author = "Apache Iggy (Incubating)",
+ version,
+ about = "Apache Iggy: Hyper-Efficient Message Streaming at Laser Speed",
+ long_about = r#"Apache Iggy (Incubating) - A persistent message streaming
platform written in Rust
+
+Apache Iggy is a high-performance message streaming platform that supports
QUIC, TCP, and HTTP
+transport protocols, capable of processing millions of messages per second
with low latency.
+
+WEBSITE:
+ https://iggy.apache.org
+
+REPOSITORY:
+ https://github.com/apache/iggy
+
+DOCUMENTATION:
+ https://iggy.apache.org/docs
+
+CONFIGURATION:
+ The server uses a TOML configuration file. By default, it looks for
'configs/server.toml'
+ in the current working directory. You can override this with the
IGGY_CONFIG_PATH environment
+ variable or use the --config-provider flag.
+
+ Examples:
+ iggy-server # Uses default file
provider (configs/server.toml)
+ iggy-server --config-provider file # Explicitly use file
provider
+ IGGY_CONFIG_PATH=custom.toml iggy-server # Use custom config
file path
+
+ENVIRONMENT VARIABLES:
+ Any configuration value can be overridden using environment variables with
the IGGY_ prefix.
+ Use underscores to separate nested configuration keys (e.g.,
IGGY_TCP_ADDRESS=127.0.0.1:8090).
+
+ Common examples:
+ IGGY_TCP_ADDRESS=0.0.0.0:8090 # Override TCP server
address
+ IGGY_HTTP_ENABLED=true # Enable HTTP transport
+ IGGY_SYSTEM_PATH=/data/iggy # Set data storage path
+ IGGY_SYSTEM_LOGGING_LEVEL=debug # Set log level to debug
+
+TRANSPORT PROTOCOLS:
+ - TCP (binary protocol): High-performance, low-latency (default:
127.0.0.1:8090)
+ - QUIC: Modern UDP-based protocol with built-in encryption (default:
127.0.0.1:8080)
+ - HTTP: RESTful API for web integration (default: 127.0.0.1:3000, disabled
by default)
+
+GETTING STARTED:
+ 1. Start the server: iggy-server
+ 2. Install CLI: cargo install iggy-cli
+ 3. Create a stream: iggy stream create my-stream
+ 4. Create a topic: iggy topic create my-stream my-topic 1 none
+ 5. Send messages: echo "Hello, Iggy!" | iggy message send my-stream
my-topic
+
+For more information, visit:
https://iggy.apache.org/docs/introduction/getting-started/"#
+)]
pub struct Args {
- #[arg(short, long, default_value = "file")]
+ /// Configuration provider type
+ ///
+ /// Currently only 'file' provider is supported, which loads configuration
from a TOML file.
+ /// The file path can be specified via IGGY_CONFIG_PATH environment
variable.
+ #[arg(short, long, default_value = "file", verbatim_doc_comment)]
pub config_provider: String,
- #[arg(
- long,
- default_value_t = false,
- help = "Remove system path (local_data by default) before starting.
THIS WILL REMOVE ALL SAVED DATA!"
- )]
+ /// Remove system path before starting (WARNING: THIS WILL DELETE ALL
DATA!)
+ ///
+ /// This flag will completely remove the system data directory (local_data
by default)
+ /// before starting the server. Use this for clean development setups or
testing.
+ ///
+ /// Examples:
+ /// iggy-server --fresh # Start with fresh data
directory
+ /// iggy-server -f # Short form
+ #[arg(short, long, default_value_t = false, verbatim_doc_comment)]
pub fresh: bool,
}
diff --git a/examples/rust/README.md b/examples/rust/README.md
index 50f93213..986f4c17 100644
--- a/examples/rust/README.md
+++ b/examples/rust/README.md
@@ -6,6 +6,19 @@ This directory contains comprehensive sample applications that
showcase various
To run any example, first start the server with `cargo run --bin iggy-server`
and then run the desired example using `cargo run --example EXAMPLE_NAME`.
+For server configuration options and help:
+
+```bash
+cargo run --bin iggy-server -- --help
+```
+
+You can also customize the server using environment variables:
+
+```bash
+## Example: Enable HTTP transport and set custom address
+IGGY_HTTP_ENABLED=true IGGY_TCP_ADDRESS=0.0.0.0:8090 cargo run --bin
iggy-server
+```
+
You can run multiple producers and consumers simultaneously to observe how
messages are distributed across clients. Most examples support configurable
options via the
[Args](https://github.com/apache/iggy/blob/master/examples/rust/src/shared/args.rs)
struct, including transport protocol, stream/topic/partition settings,
consumer ID, message size, and more.
