0
# Server Creation and Configuration
1

2
Primary entry points for creating and configuring Netty-based HTTP servers with comprehensive options for performance tuning and protocol support.
3

4
## Capabilities
5

6
### Netty Factory Object
7

8
The main factory object for creating NettyApplicationEngine instances with custom configuration.
9

10
```kotlin { .api }
11
/**
12
 * ApplicationEngineFactory providing a Netty-based ApplicationEngine
13
 */
14
object Netty : ApplicationEngineFactory<NettyApplicationEngine, NettyApplicationEngine.Configuration> {
15
    /**
16
     * Create a configuration instance with the provided configuration block
17
     * @param configure Configuration block to customize engine settings
18
     * @return Configured NettyApplicationEngine.Configuration instance
19
     */
20
    fun configuration(
21
        configure: NettyApplicationEngine.Configuration.() -> Unit
22
    ): NettyApplicationEngine.Configuration
23
    
24
    /**
25
     * Create a NettyApplicationEngine instance with the specified parameters
26
     * @param environment Application environment
27
     * @param monitor Event monitoring system  
28
     * @param developmentMode Development mode flag
29
     * @param configuration Engine configuration
30
     * @param applicationProvider Function that provides the Ktor Application
31
     * @return NettyApplicationEngine instance
32
     */
33
    fun create(
34
        environment: ApplicationEnvironment,
35
        monitor: Events,
36
        developmentMode: Boolean,
37
        configuration: NettyApplicationEngine.Configuration,
38
        applicationProvider: () -> Application
39
    ): NettyApplicationEngine
40
}
41
```
42

43
**Usage Examples:**
44

45
```kotlin
46
import io.ktor.server.engine.*
47
import io.ktor.server.netty.*
48

49
// Basic server creation
50
val server = embeddedServer(Netty, port = 8080) {
51
    // Application configuration
52
}
53

54
// Server with custom Netty configuration
55
val server = embeddedServer(Netty, port = 8080) {
56
    // Configure Netty-specific settings
57
    runningLimit = 64
58
    shareWorkGroup = true
59
    responseWriteTimeoutSeconds = 30
60
    tcpKeepAlive = true
61
    enableHttp2 = true
62
}
63
```
64

65
### Configuration Class
66

67
Comprehensive configuration options for fine-tuning Netty server behavior, performance, and protocol support.
68

69
```kotlin { .api }
70
/**
71
 * Configuration for the NettyApplicationEngine
72
 */
73
class NettyApplicationEngine.Configuration : BaseApplicationEngine.Configuration() {
74
    /**
75
     * Number of threads for connection group (inherited from BaseApplicationEngine.Configuration)
76
     * Default: 1
77
     */
78
    var connectionGroupSize: Int
79
    
80
    /**
81
     * Number of threads for worker group (inherited from BaseApplicationEngine.Configuration)
82
     * Default: Available processors
83
     */
84
    var workerGroupSize: Int
85
    
86
    /**
87
     * Number of threads for call group (inherited from BaseApplicationEngine.Configuration)
88
     * Default: Available processors
89
     */
90
    var callGroupSize: Int
91
    
92
    /**
93
     * Number of concurrently running requests from the same http pipeline
94
     * Default: 32
95
     */
96
    var runningLimit: Int
97
    
98
    /**
99
     * Do not create separate call event group and reuse worker group for processing calls
100
     * Default: false
101
     */
102
    var shareWorkGroup: Boolean
103
    
104
    /**
105
     * User-provided function to configure Netty's ServerBootstrap
106
     * Default: {} (empty function)
107
     */
108
    var configureBootstrap: ServerBootstrap.() -> Unit
109
    
110
    /**
111
     * Timeout in seconds for sending responses to client
112
     * Default: 10 seconds
113
     */
114
    var responseWriteTimeoutSeconds: Int
115
    
116
    /**
117
     * Timeout in seconds for reading requests from client, "0" is infinite
118
     * Default: 0 (infinite)
119
     */
120
    var requestReadTimeoutSeconds: Int
121
    
122
    /**
123
     * If set to true, enables TCP keep alive for connections so all
124
     * dead client connections will be discarded
125
     * Default: false
126
     */
127
    var tcpKeepAlive: Boolean
128
    
129
    /**
130
     * The url limit including query parameters
131
     * Default: HttpObjectDecoder.DEFAULT_MAX_INITIAL_LINE_LENGTH
132
     */
133
    var maxInitialLineLength: Int
134
    
135
    /**
136
     * The maximum length of all headers.
137
     * If the sum of the length of each header exceeds this value, a TooLongFrameException will be raised
138
     * Default: HttpObjectDecoder.DEFAULT_MAX_HEADER_SIZE
139
     */
140
    var maxHeaderSize: Int
141
    
142
    /**
143
     * The maximum length of the content or each chunk
144
     * Default: HttpObjectDecoder.DEFAULT_MAX_CHUNK_SIZE
145
     */
146
    var maxChunkSize: Int
147
    
148
    /**
149
     * If set to true, enables HTTP/2 protocol for Netty engine
150
     * Default: true
151
     */
152
    var enableHttp2: Boolean
153
    
154
    /**
155
     * User-provided function to configure Netty's HttpServerCodec
156
     * Default: Creates HttpServerCodec with maxInitialLineLength, maxHeaderSize, and maxChunkSize
157
     */
158
    var httpServerCodec: () -> HttpServerCodec
159
    
160
    /**
161
     * User-provided function to configure Netty's ChannelPipeline
162
     * Default: {} (empty function)
163
     */
164
    var channelPipelineConfig: ChannelPipeline.() -> Unit
165
}
166
```
167

168
**Usage Examples:**
169

170
```kotlin
171
import io.ktor.server.engine.*
172
import io.ktor.server.netty.*
173
import io.netty.bootstrap.ServerBootstrap
174
import io.netty.channel.ChannelOption
175

176
// Advanced configuration example
177
val server = embeddedServer(Netty, port = 8080) {
178
    // Thread pool configuration
179
    connectionGroupSize = 1
180
    workerGroupSize = 16
181
    callGroupSize = 32
182
    
183
    // Performance tuning
184
    runningLimit = 128
185
    shareWorkGroup = true
186
    
187
    // Timeout configuration
188
    responseWriteTimeoutSeconds = 60
189
    requestReadTimeoutSeconds = 30
190
    
191
    // Connection settings
192
    tcpKeepAlive = true
193
    
194
    // HTTP protocol limits
195
    maxInitialLineLength = 8192
196
    maxHeaderSize = 16384
197
    maxChunkSize = 8192
198
    
199
    // Protocol support
200
    enableHttp2 = true
201
    
202
    // Custom bootstrap configuration
203
    configureBootstrap = {
204
        option(ChannelOption.SO_BACKLOG, 1024)
205
        childOption(ChannelOption.SO_KEEPALIVE, true)
206
    }
207
    
208
    // Custom pipeline configuration
209
    channelPipelineConfig = {
210
        // Add custom handlers to the pipeline
211
    }
212
}
213

214
// Start the server
215
server.start(wait = true)
216
```
217

218
### Configuration Loading
219

220
Internal extension function for loading configuration from ApplicationConfig (used in EngineMain).
221

222
```kotlin { .api }
223
/**
224
 * Load configuration from ApplicationConfig
225
 * @param config ApplicationConfig instance containing deployment settings
226
 */
227
internal fun NettyApplicationEngine.Configuration.loadConfiguration(config: ApplicationConfig)
228
```
229

230
This function is used internally by `EngineMain` to load configuration from application.conf files or command line arguments. It maps configuration properties like:
231

232
- `ktor.deployment.runningLimit` → `runningLimit`
233
- `ktor.deployment.shareWorkGroup` → `shareWorkGroup`
234
- `ktor.deployment.responseWriteTimeoutSeconds` → `responseWriteTimeoutSeconds`
235
- `ktor.deployment.requestReadTimeoutSeconds` → `requestReadTimeoutSeconds`
236
- `ktor.deployment.tcpKeepAlive` → `tcpKeepAlive`
237
- `ktor.deployment.maxInitialLineLength` → `maxInitialLineLength`
238
- `ktor.deployment.maxHeaderSize` → `maxHeaderSize`
239
- `ktor.deployment.maxChunkSize` → `maxChunkSize`