Introduction

Iggy server is the most important part of the system as it's responsible for handling all the incoming connections, managing the data and providing the API for the clients. The server is written in Rust. It uses io_uring on Linux and a polling backend on macOS.

The releases are published to GitHub and can be found here. The official Docker images can be found here, use docker pull apache/iggy:0.9.0, or apache/iggy:latest for the newest stable release.

If you compile the source code in release mode, linking takes longer because LTO is enabled in the [profile.release] section of the workspace Cargo.toml.

System requirements

The server uses io_uring on Linux, which sets a minimum kernel version.

• Linux kernel 5.19 or newer is required. The shard executors create their rings with IORING_SETUP_COOP_TASKRUN and IORING_SETUP_TASKRUN_FLAG, which older kernels reject, and the server refuses to start rather than run without them. Check yours with uname -r.
• Kernel 6.1 or newer is worth having. It is the first version with the kernel.io_uring_disabled sysctl, so the startup diagnostics can tell you io_uring was disabled by policy instead of failing obscurely. See Linux tuning.
• Ubuntu 22.04 LTS ships 5.15 and will not run the server. Its hardware enablement kernel is new enough, and so are Ubuntu 24.04 LTS and Debian 12 as they ship.
• WSL2 often ships incomplete io_uring, missing setup flags or operations even on a kernel that reports 5.19 or newer. Run wsl --update first.
• macOS uses a polling backend rather than io_uring, so this requirement does not apply there.

Containers use the host's kernel, so it is the host that has to meet this requirement. See Docker & Helm.

Running the server

One iggy-server binary serves both the single-node and the clustered deployment. The loaded configuration decides which one you get. The server accepts these startup flags, plus --help and --version:

Configuration comes from the TOML file named by IGGY_CONFIG_PATH, or core/server/config.toml relative to the working directory. If that file is missing, the server uses the defaults embedded in the binary. Any key can be overridden with an IGGY_-prefixed environment variable, and a .env file in the working directory or its parents (or the file named by IGGY_ENV_PATH) is loaded at startup. See Configuration for the full reference.

When no root credentials are provided on the first single-node start, the server generates a random root password and prints it to the log. That's the only time it can be read.

The HTTP API endpoints can be found in server.http file, which can be used with REST Client extension for VS Code.

In order to see the detailed logs from the server, run it with RUST_LOG=trace environment variable.

To seed the example data, start a development server with known credentials from the root of the repository:

cargo run --bin iggy-server -- --fresh --with-default-root-credentials

In another terminal at the repository root:

cargo run --bin data-seeder-tool

The seeder logs in as iggy/iggy by default. Pass --username and --password to use other credentials.

Authentication

For broker API commands, only the ping liveness probe and the login handshake itself (username/password, personal access token, or HTTP token refresh, all of which prove a credential) are served without an authenticated session. Every other request requires one and is subject to permissions: fetching server stats, for example, needs the read_servers permission (the root user has it), and even the Prometheus /metrics scrape must present a bearer credential. A stateful connection authenticates by logging in with the user's credentials or personal access token. Logout, disconnection, or heartbeat eviction releases its session. Over the HTTP API, authentication is done by providing the Authorization header with a Bearer JWT or personal access token. HTTP CORS preflight responses and embedded /ui static assets are public; the UI's broker API calls still require authentication.