# How to Configure Connection Parameters (Host, Port, User, Password) in Kourier

> Learn how to configure Kourier connection parameters including host, port, user and password using Kotlin DSL or URL parsing. Simplify your AMQP setup.

- Repository: [Guimauve Digital/kourier](https://github.com/guimauvedigital/kourier)
- Tags: how-to-guide
- Published: 2026-03-02

---

**Kourier provides a Kotlin DSL via the `amqpConfig { ... }` builder and URL-based parsing to set AMQP connection parameters, with defaults defined in the `AMQPConfig.Server` data class.**

To configure connection parameters in the `guimauvedigital/kourier` AMQP client, you interact with a type-safe configuration hierarchy that separates connection concerns from server endpoint details. Whether you need to override the default localhost setup or connect to a production RabbitMQ cluster, Kourier offers both programmatic DSL builders and string-based URL configuration.

## Understanding Kourier's Configuration Architecture

### The AMQPConfig Data Class

At the core of Kourier's connection management lies the **`AMQPConfig`** data class defined in [`amqp-client/src/commonMain/kotlin/dev/kourier/amqp/connection/AMQPConfig.kt`](https://github.com/guimauvedigital/kourier/blob/main/amqp-client/src/commonMain/kotlin/dev/kourier/amqp/connection/AMQPConfig.kt). This immutable configuration object encapsulates all settings required to establish an AMQP connection, including transport layer options and server authentication details.

The configuration nests a **`Server`** data class that specifically holds the five parameters you need to customize:

```kotlin
data class Server(
    val host: String = Defaults.HOST,
    val port: Int = Defaults.PORT,
    val user: String = Defaults.USER,
    val password: String = Defaults.PASSWORD,
    val vhost: String = Defaults.VHOST,
    // ... additional fields like timeout
)

```

### Default Values and the Server Object

Kourier ships with sensible defaults located in the **`AMQPConfig.Server.Defaults`** companion object. By default, the client attempts to connect to:

- **Host**: `localhost`
- **Port**: `5672` (standard AMQP port)
- **User**: `guest`
- **Password**: `guest`
- **Virtual Host**: `/`

These values apply automatically when you instantiate a configuration without explicit overrides, making local development seamless.

## Method 1: Configuring via the Kotlin DSL

### Using the amqpConfig Builder

The idiomatic way to configure connection parameters is through the **`amqpConfig { ... }`** DSL extension function located in [`amqp-client/src/commonMain/kotlin/dev/kourier/amqp/connection/Extensions.kt`](https://github.com/guimauvedigital/kourier/blob/main/amqp-client/src/commonMain/kotlin/dev/kourier/amqp/connection/Extensions.kt). This function returns an `AMQPConfigBuilder` that constructs the final immutable `AMQPConfig` instance.

Behind the scenes, the DSL utilizes two builder classes:

1. **`AMQPConfigBuilder`** ([`AMQPConfigBuilder.kt`](https://github.com/guimauvedigital/kourier/blob/main/AMQPConfigBuilder.kt)) – Collects the connection type and delegates to the server builder
2. **`AMQPConfigServerBuilder`** ([`AMQPConfigServerBuilder.kt`](https://github.com/guimauvedigital/kourier/blob/main/AMQPConfigServerBuilder.kt)) – Provides mutable properties for `host`, `port`, `user`, `password`, and other server-specific settings

### Overriding Individual Server Parameters

Inside the `amqpConfig` block, invoke the `server { ... }` function to access the `AMQPConfigServerBuilder`. Here you can override any or all of the default connection parameters:

```kotlin
import dev.kourier.amqp.connection.amqpConfig
import dev.kourier.amqp.connection.createAMQPConnection
import kotlinx.coroutines.runBlocking
import kotlin.time.Duration.Companion.seconds

suspend fun connectToProduction() {
    val config = amqpConfig {
        server {
            host = "rabbitmq.production.internal"
            port = 5673
            user = "app_service"
            password = "secure_password_123"
            vhost = "production_vhost"
            timeout = 30.seconds
        }
    }
    
    val connection = createAMQPConnection(coroutineScope = this, config = config)
    // Connection established with custom parameters
}

fun main() = runBlocking { connectToProduction() }

```

The builder pattern ensures that only the fields you explicitly set deviate from the defaults, keeping configuration concise and maintainable.

## Method 2: URL-Based Configuration

### Parsing AMQP URLs

For scenarios where you store connection strings in environment variables or configuration files, Kourier supports **AMQP URL parsing**. The same [`Extensions.kt`](https://github.com/guimauvedigital/kourier/blob/main/Extensions.kt) file provides an overload that accepts a `Url` object or string in the format:

```

amqp://user:password@host:port/vhost

```

When you call `amqpConfig(url)`, the library extracts the authentication credentials and endpoint details, falling back to the standard defaults for any missing components:

```kotlin
import dev.kourier.amqp.connection.amqpConfig
import dev.kourier.amqp.connection.createAMQPConnection
import kotlinx.coroutines.runBlocking

suspend fun connectViaUrl() {
    val connectionString = "amqp://app_user:secret123@mq.example.com:5672/app_vhost"
    
    val config = amqpConfig(connectionString)
    val connection = createAMQPConnection(this, config)
    
    val channel = connection.openChannel()
    channel.queueDeclare("tasks", durable = true, exclusive = false, autoDelete = false, arguments = emptyMap())
}

fun main() = runBlocking { connectViaUrl() }

```

This approach is particularly useful for containerized deployments where the connection string is injected via environment variables.

## Applying the Configuration to Create Connections

### From Config to Connection

Once you have an `AMQPConfig` instance—whether built via DSL or parsed from a URL—you pass it to **`createAMQPConnection(coroutineScope, config)`**. This function, also defined in [`Extensions.kt`](https://github.com/guimauvedigital/kourier/blob/main/Extensions.kt), instantiates a `DefaultAMQPConnection`.

The `DefaultAMQPConnection` class ([`amqp-client/src/commonMain/kotlin/dev/kourier/amqp/connection/DefaultAMQPConnection.kt`](https://github.com/guimauvedigital/kourier/blob/main/amqp-client/src/commonMain/kotlin/dev/kourier/amqp/connection/DefaultAMQPConnection.kt)) consumes the `config.server` fields during its `connect()` method. Specifically, it passes `config.server.host` and `config.server.port` to the underlying TCP client, then uses `config.server.user` and `config.server.password` to authenticate the AMQP handshake:

```kotlin
// Simplified view of the connection logic
suspend fun connect() {
    val socket = tcpClient.connect(
        hostname = config.server.host,
        port = config.server.port
    )
    // ... perform AMQP protocol handshake using user/password
}

```

## Summary

- **Kourier** stores connection parameters in the immutable `AMQPConfig.Server` data class with defaults for localhost development.
- Use the **`amqpConfig { server { ... } }`** DSL in [`Extensions.kt`](https://github.com/guimauvedigital/kourier/blob/main/Extensions.kt) for type-safe, programmatic configuration of host, port, user, and password.
- Pass connection strings to **`amqpConfig(url)`** for URL-based configuration following the `amqp://user:pass@host:port/vhost` format.
- Supply the resulting `AMQPConfig` to **`createAMQPConnection()`** to instantiate a `DefaultAMQPConnection` that reads these parameters during socket creation.
- All configuration builders reside in `amqp-client/src/commonMain/kotlin/dev/kourier/amqp/connection/` with clear separation between the immutable config ([`AMQPConfig.kt`](https://github.com/guimauvedigital/kourier/blob/main/AMQPConfig.kt)), mutable builders ([`AMQPConfigBuilder.kt`](https://github.com/guimauvedigital/kourier/blob/main/AMQPConfigBuilder.kt), [`AMQPConfigServerBuilder.kt`](https://github.com/guimauvedigital/kourier/blob/main/AMQPConfigServerBuilder.kt)), and entry points ([`Extensions.kt`](https://github.com/guimauvedigital/kourier/blob/main/Extensions.kt)).

## Frequently Asked Questions

### How do I set a custom port for my RabbitMQ connection in Kourier?

Inside the `amqpConfig` DSL block, nest a `server` block and assign an integer to the `port` property. For example: `server { port = 5673 }`. This overrides the default value of `5672` defined in `AMQPConfig.Server.Defaults.PORT`.

### Can I configure Kourier connection parameters using environment variables?

Yes. Parse the environment variable as a URL string and pass it to `amqpConfig(urlString)`. Alternatively, read individual environment variables and assign them within the `server { ... }` builder block using standard Kotlin string interpolation or `System.getenv()` calls.

### What is the default virtual host in Kourier, and how do I change it?

The default virtual host is `/` (root), defined in `AMQPConfig.Server.Defaults.VHOST`. To change it, set the `vhost` property in the server builder: `server { vhost = "my_custom_vhost" }`.

### Where does Kourier actually use the password and username to authenticate?

The `DefaultAMQPConnection` class in [`DefaultAMQPConnection.kt`](https://github.com/guimauvedigital/kourier/blob/main/DefaultAMQPConnection.kt) reads `config.server.user` and `config.server.password` during the connection initialization phase to perform the AMQP protocol handshake with the broker.