diff --git a/.DS_Store b/.DS_Store index c16f49fd6..855c4b071 100644 Binary files a/.DS_Store and b/.DS_Store differ diff --git a/codeSnippets/snippets/embedded-server/build.gradle.kts b/codeSnippets/snippets/embedded-server/build.gradle.kts index 782c2ed18..dedc5f262 100644 --- a/codeSnippets/snippets/embedded-server/build.gradle.kts +++ b/codeSnippets/snippets/embedded-server/build.gradle.kts @@ -29,6 +29,9 @@ dependencies { implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version") implementation("io.ktor:ktor-server-core:$ktor_version") implementation("io.ktor:ktor-server-netty:$ktor_version") + implementation("io.ktor:ktor-server-jetty-jakarta:$ktor_version") + implementation("io.ktor:ktor-server-cio:$ktor_version") + implementation("io.ktor:ktor-server-tomcat-jakarta:$ktor_version") implementation("ch.qos.logback:logback-classic:$logback_version") testImplementation("junit:junit:$junit_version") diff --git a/codeSnippets/snippets/embedded-server/src/main/kotlin/com/example/Application.kt b/codeSnippets/snippets/embedded-server/src/main/kotlin/com/example/Application.kt index 2b5d5c024..e5a6db9b7 100644 --- a/codeSnippets/snippets/embedded-server/src/main/kotlin/com/example/Application.kt +++ b/codeSnippets/snippets/embedded-server/src/main/kotlin/com/example/Application.kt @@ -69,4 +69,49 @@ fun runServerWithCommandLineConfig(args: Array) { } } }.start(wait = true) -} \ No newline at end of file +} + +fun runConfiguredCommonProperties() { + embeddedServer(Netty, configure = { + connector { + host = "0.0.0.0" + port = 8080 + } + connectionGroupSize = 2 + workerGroupSize = 5 + callGroupSize = 10 + shutdownGracePeriod = 2000 + shutdownTimeout = 3000 + }) { + module() + }.start(wait = true) +} + +fun io.ktor.server.application.Application.module() { + routing { + get("/") { + call.respondText("Hello, world!") + } + } +} + +fun runConfiguredNettyProperties() { + embeddedServer(Netty, configure = { + runningLimit = 16 + shareWorkGroup = false + configureBootstrap = { + // ... + } + channelPipelineConfig = { + // + } + responseWriteTimeoutSeconds = 10 + requestReadTimeoutSeconds = 0 // infinite + tcpKeepAlive = false + maxInitialLineLength = 4096 + maxHeaderSize = 8192 + maxChunkSize = 8192 + }) { + module() + }.start(true) +} diff --git a/codeSnippets/snippets/embedded-server/src/main/kotlin/com/example/CIO.kt b/codeSnippets/snippets/embedded-server/src/main/kotlin/com/example/CIO.kt new file mode 100644 index 000000000..da8d347bc --- /dev/null +++ b/codeSnippets/snippets/embedded-server/src/main/kotlin/com/example/CIO.kt @@ -0,0 +1,13 @@ +package com.example + +import io.ktor.server.cio.CIO +import io.ktor.server.engine.embeddedServer + +fun runConfiguredCIOProperties() { + embeddedServer(CIO, configure = { + connectionIdleTimeoutSeconds = 45 + reuseAddress = false + }) { + module() + }.start(true) +} diff --git a/codeSnippets/snippets/embedded-server/src/main/kotlin/com/example/Jetty.kt b/codeSnippets/snippets/embedded-server/src/main/kotlin/com/example/Jetty.kt new file mode 100644 index 000000000..4ef9ef747 --- /dev/null +++ b/codeSnippets/snippets/embedded-server/src/main/kotlin/com/example/Jetty.kt @@ -0,0 +1,19 @@ +package com.example + +import io.ktor.server.engine.embeddedServer +import io.ktor.server.jetty.jakarta.Jetty +import org.eclipse.jetty.server.handler.ErrorHandler +import kotlin.time.Duration.Companion.seconds + +fun runConfiguredJettyProperties() { + embeddedServer(Jetty, configure = { + configureServer = { + errorHandler = MyErrorHandler() + } + idleTimeout = 30.seconds + }) { + module() + }.start(true) +} + +class MyErrorHandler : ErrorHandler() \ No newline at end of file diff --git a/codeSnippets/snippets/embedded-server/src/main/kotlin/com/example/Tomcat.kt b/codeSnippets/snippets/embedded-server/src/main/kotlin/com/example/Tomcat.kt new file mode 100644 index 000000000..045f88616 --- /dev/null +++ b/codeSnippets/snippets/embedded-server/src/main/kotlin/com/example/Tomcat.kt @@ -0,0 +1,17 @@ +package com.example + +import io.ktor.server.engine.embeddedServer +import io.ktor.server.tomcat.jakarta.Tomcat + +fun runConfiguredTomcatProperties() { + embeddedServer(Tomcat, configure = { + configureTomcat = { + with(connector) { + enableLookups = false + setProperty("maxThreads", "150") + } + } + }) { + module() + }.start(true) +} \ No newline at end of file diff --git a/ktor.tree b/ktor.tree index 7cb28af89..2936fe472 100644 --- a/ktor.tree +++ b/ktor.tree @@ -47,10 +47,9 @@ - - + Configuration : Choose whether - to specify server parameters in a YAML or HOCON file, or - in code. + to specify server parameters in a YAML or HOCON file, or + in code.

diff --git a/topics/migrating-3.md b/topics/migrating-3.md index 3067c5266..8e9c91875 100644 --- a/topics/migrating-3.md +++ b/topics/migrating-3.md @@ -139,7 +139,7 @@ fun main(args: Array) { For more information on command-line configuration with `embeddedServer`, see the -[Configuration in code](server-configuration-code.topic#command-line) topic. +[Configuration in code](server-engines.md#configure-engine) topic. #### Introduction of `ServerConfigBuilder` {id="ServerConfigBuilder"} diff --git a/topics/server-configuration-code.topic b/topics/server-configuration-code.topic deleted file mode 100644 index b3ceb5c0c..000000000 --- a/topics/server-configuration-code.topic +++ /dev/null @@ -1,268 +0,0 @@ - - - - - - - - - Learn how to configure various server parameters in code. - - -

- Ktor allows you to configure various server parameters directly in code, including the host address, port, server modules, and more. The method of configuration depends on the - way you set up a server - using embeddedServer - or EngineMain. -

-

- With embeddedServer, you configure the server by passing the desired parameters directly to - the function. - The - - embeddedServer - - function accepts different parameters for configuring a server, including a server - engine, the host and port for the server to listen on, and additional configurations. -

-

- In this section, we'll take a look at several different examples of running embeddedServer, - illustrating how you can configure the server to your advantage. -

- -

- The code snippet below shows a basic server setup with the Netty engine and the 8080 port. -

- -

- Note that you can set the port parameter to 0 to run the server on a random port. - The embeddedServer function returns an engine instance, so you can get a port value in code - using the - - ApplicationEngine.resolvedConnectors - - function. -

- - - - -

- The embeddedServer function allows you to pass engine-specific options using the - configure parameter. This parameter includes options common for all engines and exposed by - the - - ApplicationEngine.Configuration - - class. -

-

- The example below shows how to configure a server using the Netty engine. Within the - configure block, we define a connector to specify the host and port, and - customize various server parameters: -

- -

- The connectors.add() method defines a connector with the specified host - (127.0.0.1) - and port (8080). -

-

In addition to these options, you can configure other engine-specific properties.

- -

- Netty-specific options are exposed by the - - NettyApplicationEngine.Configuration - - class. -

- - - -

- Jetty-specific options are exposed by the - - JettyApplicationEngineBase.Configuration - - class. -

-

You can configure the Jetty server inside the - - configureServer - - block, which provides access to a - Server - instance. -

-

- Use the idleTimeout property to specify the duration of time a connection can be idle - before it gets closed. -

- - - -

CIO-specific options are exposed by the - - CIOApplicationEngine.Configuration - - class. -

- - - -

If you use Tomcat as the engine, you can configure it using the - - configureTomcat - - property, which provides access to a - Tomcat - instance. -

- - - - - - -

- The example below shows how to run a server with multiple connector endpoints - using a custom configuration represented by the - - ApplicationEngine - - interface. -

- - - -

- For the complete example, see - - embedded-server-multiple-connectors - . -

- - -

- You can also use a custom environment to - - serve HTTPS - . -

- - - -

- Ktor allows you to dynamically configure an embeddedServer using command-line arguments. This - can be particularly useful in cases where configurations like ports, hosts, or timeouts need to be - specified at runtime. -

-

- To achieve this, use the - - CommandLineConfig - - class to parse command-line arguments into a configuration object and pass it within the configuration - block: -

- -

- In this example, the - - takeFrom() - - function from Application.Configuration is used to override engine configuration values, such - as port and host. - The - - loadCommonConfiguration() - - function loads configuration from the root environment, such as timeouts. -

-

- To run the server, specify arguments in the following way: -

- - ./gradlew run --args="-port=8080" - - - For static configurations, you can use a configuration file or environment variables. - To learn more, see - - Configuration in a file - - . - - - \ No newline at end of file diff --git a/topics/server-configuration-file.topic b/topics/server-configuration-file.topic deleted file mode 100644 index b74cdb4b3..000000000 --- a/topics/server-configuration-file.topic +++ /dev/null @@ -1,601 +0,0 @@ - - - - - - - - - Learn how to configure various server parameters in a configuration file. - - -

- Ktor allows you to configure various server parameters, such as a host address and port, - modules - to load, and so on. - The configuration depends on the way you used to create a server - - - embeddedServer or EngineMain - - . -

-

- For EngineMain, Ktor loads its configuration from a configuration file that uses the - - HOCON - - or YAML format. This way provides more flexibility to configure a server and allows you to change a - configuration without recompiling your application. Moreover, you can run your application from a command line - and override the required server parameters by passing corresponding - - command-line - - arguments. -

- -

- If you use - - EngineMain - - to start a server, Ktor loads configuration settings automatically from a file named - application.* - located in the - resources - directory. Two configuration formats are supported: -

- -
  • -

    - HOCON ( - application.conf - ) -

    -
    • -
  • -

    - YAML ( - application.yaml - ) -

    - -

    - To use a YAML configuration file, you need to add the ktor-server-config-yaml - - dependency - - . -

    -     -
    • -     -

    - A configuration file should contain at least - - modules to load - - specified using the ktor.application.modules property, for example: -

    - - - - - - - - - -

    - In this case, Ktor calls the Application.module function in the - Application.kt - file below: -

    - - -

    - Besides modules to load, you can configure various server settings, including - predefined - (such as a port or host, SSL settings, etc.) and custom ones. - Let's take a look at several examples. -

    - - -

    - In the example below, a server listening port is set to 8080 using the - ktor.deployment.port property. -

    - - - - - - - - -     - - -

    - If you use EngineMain, you can specify options common for all engines within the - ktor.deployment group. -

    - - - - - - - - - -

    - You can also configure Netty-specific options in a configuration file within the - ktor.deployment group: -

    - - - - - - - - -     -     -     - - -

    - The example below enables Ktor to listen on the 8443 SSL port and specifies the required - - SSL settings - - in a separate security block. -

    - - - - - - - - -     - - -

    - Apart from specifying the predefined properties, - Ktor allows you to keep custom settings in the configuration file. - The configuration files below contain a custom jwt group used to keep - JWT - settings. -

    - - - - - - - - -

    - You can read and handle such settings in code. -

    - -

    - Note that sensitive data (like secret keys, database connection settings, and so on) should not be - stored in the configuration file as plain text. Consider using - - environment variables - - to specify such parameters. -

    -     -     -     - - - -

    - Below is a list of predefined settings that you can use inside a - - configuration file - . -

    - - -

    - A host address. -

    -

    - Example - : 0.0.0.0 -

    -     - -

    - A listening port. You can set this property to 0 to run the server on a random port. -

    -

    - Example - : 8080, 0 -

    -     - -

    - A listening SSL port. You can set this property to 0 to run the server on a random - port. -

    -

    - Example - : 8443, 0 -

    - -

    - Note that SSL requires additional options listed below. -

    -     -     - -

    - Watch paths used for auto-reloading. -

    -     - -

    - A servlet context path. -

    -

    - Example - : / -

    -     - -

    - A shutdown URL. - Note that this option uses the plugin. -

    -     - -

    - A maximum time in milliseconds for a server to stop accepting new requests. -

    -     - -

    - A maximum time in milliseconds to wait until the server stops completely. -

    -     - -

    - A minimum size of a thread pool used to process application calls. -

    -     - -

    - A count of threads used to accept new connections and start call processing. -

    -     - -

    - A size of the event group for processing connections, parsing messages, and doing the engine's - internal work. -

    -     -     -

    - If you've set ktor.deployment.sslPort, you need to specify the following - - SSL-specific - - properties: -

    - - -

    - An SSL key store. -

    -     - -

    - An alias for the SSL key store. -

    -     - -

    - A password for the SSL key store. -

    -     - -

    - A password for the SSL private key. -

    -     -     -     - - - -

    - In a configuration file, you can substitute parameters with environment variables by using the - ${ENV} / $ENV syntax. - For example, you can assign the PORT environment variable to the - ktor.deployment.port property in the following way: -

    - - - - - - - - - -

    - In this case, an environment variable value will be used to specify a listening port. - If the PORT environment variable variable doesn't exist at runtime, you can provide a default - port value as follows: -

    - - - - - - - - -     - -

    - Ktor allows you to access property values specified inside a configuration file in code. - For example, if you've specified the ktor.deployment.port property,... -

    - - - - - - - - - - -

    - ... you can access the application's configuration using - - ApplicationEnvironment.config - - and get the required property value in the following way: -

    - -

    - This is especially useful when you keep custom settings in a configuration - file and need to access its values. -

    -     - - -

    - If you use EngineMain to create a - server, you can run a packaged application from a command line and override - the required server parameters by passing corresponding command-line arguments. For example, you can - override a port specified in a configuration file in the following way: -

    - - java -jar sample-app.jar -port=8080 - -

    - The available command-line options are listed below: -

    - - -

    - A path to JAR file. -

    -     - -

    - A path to a custom configuration file used instead of - application.conf - / - application.yaml - from resources. -

    -

    - Example - : java -jar sample-app.jar -config=anotherfile.conf -

    -

    - Note - : You can pass multiple values. java -jar sample-app.jar -config=config-base.conf - -config=config-dev.conf. In this case all configs will be merged, where values from configs - on the right will have priority. -

    - -     - -

    - A host address. -

    -     - -

    - A listening port. -

    -     - -

    - Watch paths used for auto-reloading. -

    -     -     -

    - SSL-specific options: -

    - - -

    - A listening SSL port. -

    -     - -

    - An SSL key store. -

    -     -     -

    - If you need to override a predefined property - that doesn't have a corresponding command-line option, use the -P flag, for example: -

    - - java -jar sample-app.jar -P:ktor.deployment.callGroupSize=7 - -

    - You can also use the -P flag to override a custom property. -

    -     - - - -

    - You might want to do different things depending on whether a server is running locally or on a production - machine. To achieve this, you can add a custom property in - application.conf - / - application.yaml - and initialize it with a dedicated environment variable whose value - depends on whether a server is running locally or on production. In the example below, the - KTOR_ENV environment variable is assigned to a custom ktor.environment property. -

    - - - - - - - - - - -

    - You can access the ktor.environment value at runtime by - - reading configuration in code - - and perform the required actions: -

    - -

    - You can find the full example here: - - engine-main-custom-environment - . -

    -     - -     \ No newline at end of file diff --git a/topics/server-configuration.md b/topics/server-configuration.md new file mode 100644 index 000000000..eabc110fb --- /dev/null +++ b/topics/server-configuration.md @@ -0,0 +1,244 @@ +[//]: # (title: Application Configuration) + + + + +Learn how to configure various engine, and custom application parameters in code and file-based configurations. + + +When running a Ktor server application, you might need to configure Ktor and application-specific configuration. +These kinds of configurations are unrelated to [Engine Configuration][server-engines.md] and allow configuring Ktor +itself or your own configurations required for your application. + +### Overview {id="configuration-overview"} + +Ktor supports loading [HOCON](https://github.com/lightbend/config/blob/master/HOCON.md) and [YAML](https://yaml.org) +configuration files out-of-the-box. +If you use [EngineMain](server-create-and-configure.topic#engine-main) to start a server, Ktor will automatically load +`application.conf` or `application.yaml` respectively. +[EmbeddedServer](server-create-and-configure.topic#embedded-server) will not automatically load any configuration files, +but you can rely on `ApplicationConfig` directly to load them manually. + + +To use a YAML configuration file, you need to add the `ktor-server-config-yaml` [dependency](#server-dependencies.topic). + + +Both `YAML` and `HOCON` support environment variable substitution using `"$NAME:fallback"` syntax. This is convenient as +it allows us to easily parameterize configuration values and provide fallback values. +For more complex use-cases you can also load [environment-specific configuration files](#environment-config) or override +configuration values by passing [command-line arguments](#command-line). + +When working with `ApplicationConfig` directly, we can use `getAs` to retrieve a deserialized `DatabaseConfig` from our +loaded configurations. `EngineMain` can rely on the `application.yaml` that was automatically loaded. + + + + +```kotlin +@Serializable +data class DatabaseConfig( + val jdbcUrl: String, + val username: String, + val password: String +) + +embeddedServer(Netty) { + val config = ApplicationConfig("application.yaml") + val databaseConfig = config.property("database") + .getAs() +} +``` + + + + +```kotlin +@Serializable +data class DatabaseConfig( + val jdbcUrl: String, + val username: String, + val password: String +) + +fun Application.module() { + val databaseConfig = property("database") +} +``` + + + + +```yaml +database: + jdbcUrl: "$DB_JDBC_URL:jdbc:postgresql://localhost/ktor_database" + username: "$DB_USERNAME:ktor_user" + password: "$DB_PASSWORD:ktor_password" +``` + + + + +```yaml +database { + jdbcUrl="$DB_JDBC_URL:jdbc:postgresql://localhost/ktor_database" + username="$DB_USERNAME:ktor_user" + password="$DB_PASSWORD:ktor_password" +} +``` + + + + +### Layered Configuration Files {id="layered-config"} + +In some cases it's desired to _split_ configuration files based on the environment to prevent a fallback value from +being used in production. +Or to define a _main_ configuration and only override specific keys depending on the environment. The configuration +below defines an `application.yaml` which holds our _base_ configuration. +The environment-specific files can override key-value pairs defined by the _base_ configuration. +In this case `application-prod.yaml` overrides the `loglevel`, whilst loading `application-test.yaml` will override +`database` and configure an additional `dev-only-key` configuration value. + + + + +```yaml +ktor: + application.modules: + - org.jetbrains.Application.module + +database: + jdbcUrl: "$DB_JDBC_URL" + username: "$DB_USERNAME" + password: "$DB_PASSWORD" + +loglevel: INFO +``` + + + + +```yaml +loglevel: ERROR +``` + + + + +```yaml +database: + jdbcUrl: "jdbc:postgresql://localhost/ktor_database" + username: "ktor_user" + password: "ktor_password" + +dev-only-key: "Extra configuration only available in test" +``` + + + + +`embeddedServer` doesn't load any files by itself, we first load `application.yaml`, and we `mergeWith` our +environment-specific configuration file. +`mergeWith` will override any existing keys from the original configuration and add all non-existing ones. +When overriding which files `EngineMain` should load, we need to specify _all_ files. Most conveniently, this is done by +passing CLI arguments specific for your environment, but this can also be done through code by explicitly setting the +arguments. + + + + +```kotlin +@Serializable +enum class LogLevel { ERROR, INFO; } + +@Serializable +data class AppConfig(val level: LogLevel, val database: DatabaseConfig) + +embeddedServer(Netty) { + val env = System.getenv("ENV") ?: "test" + val config = ApplicationConfig("application.yaml") + .mergeWith(ApplicationConfig("application-$env.yaml")) + val appConfig = config.property("app").getAs() +} +``` + + + + +```kotlin +@Serializable +data class DatabaseConfig( + val jdbcUrl: String, + val username: String, + val password: String +) + +fun main(args: Array) { + val environment = System.getenv("KTOR_ENVIRONMENT") ?: "test" + val configs = arrayOf( + "-config=application.yaml", + "-config=application-$environment.yaml" + ) + EngineMain.main(args + configs) +} + +fun Application.module() { + val appConfig = property("app") +} +``` + + + + +```shell +java -jar sample-app.jar -config=application.conf,application-prod.conf +``` + + + + +### Command-line arguments {id="command-line"} + +When working with `EngineMain` ktor allows you to override configuration properties using command-line arguments. +This is useful when you need to change the configuration without modifying the configuration file. + +To override a property, use the `-P:` prefix followed by the property path and value: + +```shell +java -jar sample-app.jar -P:ktor.deployment.port=8080 +``` + +In this example, we override the `ktor.deployment.port` property with the value `8080`. + +You can also use environment variables to override properties: + +```shell +PORT=8080 java -jar sample-app.jar +``` + +In this example, we set the `PORT` environment variable, which will be used if the configuration file contains +`${?PORT}` as shown in the [ktor.deployment](#deployment) section. + +#### Multiple configuration files {id="multiple-configuration-files"} + +Ktor allows you to use multiple configuration files. This is useful when you need to have different configurations for +different environments (development, testing, production). + +To specify a configuration file, use the `-config=` command-line argument: + +```shell +java -jar sample-app.jar -config=application-prod.conf +``` + +In this example, we use the `application-prod.conf` file instead of the default `application.conf`. + +You can also combine multiple configuration files: + +```shell +java -jar sample-app.jar -config=application.conf,application-prod.conf +``` + +In this case, properties from `application-prod.conf` will override properties from `application.conf` if they have the +same path. + + diff --git a/topics/server-create-and-configure.topic b/topics/server-create-and-configure.topic index 2ae2c34fe..36adaf707 100644 --- a/topics/server-create-and-configure.topic +++ b/topics/server-create-and-configure.topic @@ -90,7 +90,7 @@

    The embeddedServer function is a simple way to configure server parameters in - code + code and quickly run an application. In the code snippet below, it accepts an engine and port as parameters to start a server. In the example below, we run a server with the diff --git a/topics/server-engines.md b/topics/server-engines.md index 6b61f78b2..ee310a034 100644 --- a/topics/server-engines.md +++ b/topics/server-engines.md @@ -6,40 +6,30 @@ Learn about engines that process network requests. -To run a Ktor server application, you need to [create](server-create-and-configure.topic) and configure a server first. -Server configuration includes different settings: -- an [engine](#supported-engines) for processing network requests; -- host and port values used to access a server; -- SSL settings; -- ... and so on. - -## Supported engines {id="supported-engines"} - -The table below lists engines supported by Ktor, along with the supported platforms: - -| Engine | Platforms | HTTP/2 | -|-----------------------------------------|------------------------------------------------------|--------| -| `Netty` | JVM | ✅ | -| `Jetty` | JVM | ✅ | -| `Tomcat` | JVM | ✅ | -| `CIO` (Coroutine-based I/O) | JVM, [Native](server-native.md), [GraalVM](graalvm.md) | ✖️ | -| [ServletApplicationEngine](server-war.md) | JVM | ✅ | - ## Add dependencies {id="dependencies"} -Before using the desired engine, you need to add the corresponding dependency to -your [build script](server-dependencies.topic): +Before using the desired engine, you need to add the corresponding dependency to your [build script](server-dependencies.topic): * `ktor-server-netty` * `ktor-server-jetty-jakarta` * `ktor-server-tomcat-jakarta` * `ktor-server-cio` + Below are examples of adding a dependency for Netty: +Which is the most popular engine, and recommended JVM engine for Ktor. + +To run a Ktor server application, you need to [create](server-create-and-configure.topic) and configure a server first. +Server configuration includes different settings: +- an [engine](#supported-engines) for processing network requests; +- host and port values used to access a server; +- SSL settings; +- ... and so on. + ## Choose how to create a server {id="choose-create-server"} A Ktor server application can be [created and run in two ways](server-create-and-configure.topic#embedded): using the [embeddedServer](#embeddedServer) to quickly pass server parameters in code, or using [EngineMain](#EngineMain) to @@ -136,10 +126,192 @@ mainClassName = "io.ktor.server.netty.EngineMain" In this section, we'll take a look at how to specify various engine-specific options. -### In code {id="embedded-server-configure"} +### Common Configuration + +Depending on how you [create your server](#choose-create-server) you can pass engine-specific options. +This can be done through the `configure` DSL for `embeddedServer`, which includes common options for all engines exposed by the [ApplicationEngine.Configuration](https://api.ktor.io/ktor-server/ktor-server-core/io.ktor.server.engine/-application-engine/-configuration/index.html) class. +`EngineMain` defines its configuration in `application.yaml` as shown below. - + + -### In a configuration file {id="engine-main-configure"} +```kotlin +``` + +{src="snippets/embedded-server/src/main/kotlin/com/example/Application.kt" include-lines="75-88"} + + + + +``` +ktor { + deployment { + port = 8080 + connectionGroupSize = 2 + workerGroupSize = 5 + callGroupSize = 10 + shutdownGracePeriod = 2000 + shutdownTimeout = 3000 + } + application { + modules = [ com.example.ApplicationKt.module ] + } +} +``` + + + + +```yaml +ktor: + deployment: + port: 8080 + connectionGroupSize: 2 + workerGroupSize: 5 + callGroupSize: 10 + shutdownGracePeriod: 2000 + shutdownTimeout: 3000 + application: + modules: + - com.example.ApplicationKt.module +``` + + + + +In addition to these options, you can configure other engine-specific properties. + +### Netty {id="netty-code"} + +Netty-specific options are exposed by the [NettyApplicationEngine.Configuration](https://api.ktor.io/ktor-server/ktor-server-netty/io.ktor.server.netty/-netty-application-engine/-configuration/index.html) class. +The [NettyApplicationEngine.Configuration](https://api.ktor.io/ktor-server/ktor-server-netty/io.ktor.server.netty/-netty-application-engine/-configuration/index.html) properties are also available under `ktor.deployment` for file-based configuration. + + + + +```kotlin +``` + +{src="snippets/embedded-server/src/main/kotlin/com/example/Application.kt" include-lines="99-116"} + + + + +``` +ktor { + deployment { + host = "0.0.0.0" + port = 8080 + runningLimit = 16 + shareWorkGroup = false + responseWriteTimeoutSeconds = 10 + requestReadTimeoutSeconds = 0 + tcpKeepAlive = false + maxInitialLineLength = 4096 + maxHeaderSize = 8192 + maxChunkSize = 8192 + } + application { + modules = [ com.example.ApplicationKt.module ] + } +} +``` + + + + +```yaml +ktor: + application.modules: + - org.jetbrains.Application.module + deployment: + host: 0.0.0.0 + port: 8080 + runningLimit: 16 + shareWorkGroup: false + responseWriteTimeoutSeconds: 10 + requestReadTimeoutSeconds: 0 + tcpKeepAlive: false + maxInitialLineLength: 4096 + maxHeaderSize: 8192 + maxChunkSize: 8192 +``` + + + +### CIO {id="cio-code"} + +CIO-specific options are exposed by the [CIOApplicationEngine.Configuration](https://api.ktor.io/ktor-server/ktor-server-cio/io.ktor.server.cio/-c-i-o-application-engine/-configuration/index.html) class. +The [CIOApplicationEngine.Configuration](https://api.ktor.io/ktor-server/ktor-server-cio/io.ktor.server.cio/-c-i-o-application-engine/-configuration/index.html) properties are also available under `ktor.deployment` for file-based configuration. + + + + +```kotlin +``` +{src="snippets/embedded-server/src/main/kotlin/com/example/CIO.kt" include-lines="7-12"} + + + + +``` +ktor { + deployment { + host = "0.0.0.0" + port = 8080 + connectionIdleTimeoutSeconds: 45 + } + application { + modules = [ com.example.ApplicationKt.module ] + } +} +``` + + + + +```yaml +ktor: + application.modules: + - org.jetbrains.Application.module + deployment: + host: 0.0.0.0 + port: 8080 + connectionIdleTimeoutSeconds: 45 +``` + + + +### Jetty {id="jetty-code"} + +Jetty-specific options are exposed by the [JettyApplicationEngineBase.Configuration](https://api.ktor.io/ktor-server/ktor-server-jetty-jakarta/io.ktor.server.jetty.jakarta/-jetty-application-engine-base/-configuration/index.html) class. +You can configure the Jetty server inside the [configureServer](https://api.ktor.io/ktor-server/ktor-server-jetty-jakarta/io.ktor.server.jetty.jakarta/-jetty-application-engine-base/-configuration/configure-server.html) block, which provides access to a [Server](https://www.eclipse.org/jetty/javadoc/jetty-11/org/eclipse/jetty/server/Server.html) instance. +Use the `idleTimeout` property to specify the duration of time a connection can be idle before it gets closed. + +There is no special support for configuring Jetty from file-based configurations. + +```kotlin +``` +{src="snippets/embedded-server/src/main/kotlin/com/example/Jetty.kt" include-lines="9-16"} + +### Tomcat {id="tomcat-code"} + +If you use Tomcat as the engine, you can configure it using the [configureTomcat](https://api.ktor.io/ktor-server/ktor-server-tomcat-jakarta/io.ktor.server.tomcat.jakarta/-tomcat-application-engine/-configuration/configure-tomcat.html) property, which provides access to a [Tomcat](https://tomcat.apache.org/tomcat-10.1-doc/api/org/apache/catalina/startup/Tomcat.html) instance. +There is no special support for configuring Tomcat from file-based configurations. + +```kotlin +``` +{src="snippets/embedded-server/src/main/kotlin/com/example/Tomcat.kt" include-lines="7-16"} + +## Supported engines {id="supported-engines"} + +The table below lists engines supported by Ktor, along with the supported platforms: + +| Engine | Platforms | HTTP/2 | +|-----------------------------------------|------------------------------------------------------|--------| +| `Netty` | JVM | ✅ | +| `Jetty` | JVM | ✅ | +| `Tomcat` | JVM | ✅ | +| `CIO` (Coroutine-based I/O) | JVM, [Native](server-native.md), [GraalVM](graalvm.md) | ✖️ | +| [ServletApplicationEngine](server-war.md) | JVM | ✅ | - \ No newline at end of file diff --git a/topics/server-ssl.md b/topics/server-ssl.md index b1c54ce61..d358cdd2c 100644 --- a/topics/server-ssl.md +++ b/topics/server-ssl.md @@ -138,7 +138,7 @@ see [ssl-engine-main](https://github.com/ktorio/ktor-documentation/tree/%ktor_ve ### embeddedServer {id="embedded-server"} If you use the `embeddedServer` function to run your server, you need to configure -a [custom environment](server-configuration-code.topic#embedded-custom) in +a [custom environment](server-engines.md#configure-engine) in the [ApplicationEngine.Configuration](https://api.ktor.io/ktor-server/ktor-server-core/io.ktor.server.engine/-application-engine/-configuration/index.html) and provide SSL settings there diff --git a/topics/welcome.topic b/topics/welcome.topic index 446bb4c2c..1f2a0029d 100644 --- a/topics/welcome.topic +++ b/topics/welcome.topic @@ -42,8 +42,7 @@ - - +