Getting Started

In this short tutorial we will overview the steps of creating a Kotless-based application.

Preliminaries

To use Kotless in your project you need:

• Kotlin version 1.3.50+
• Administrative access to AWS account (e.g. profile in .aws/.credentials)
• Route53 DNS zone to create DNS name for the application
• S3 bucket to store kotless-related artifacts
• ACM certificate for DNS name at US-EAST-1 (N. Virginia)

Setting up Gradle project

First of all, you need to set up Gradle for your project. Kotless uses Gradle tasks to prepare deployment environment, generate deployment code, prepare a jar and deploy it to cloud provider.

You need to apply a plugin to project at build.gradle.kts:

id("io.kotless") version "0.1.1" apply true

To use Kotless DSL in a project you need to set up a maven repository with DSL and add the necessary dependency:

repositories {
    jcenter()
}
dependencies {
    implementation("io.kotless", "lang", "0.1.1")
}

Next, you need to set up Kotless. Here is a simple configuration with comments:

kotless {
    config {
        //bucket that kotless will use to store its artifacts
        bucket = "kotless-example-bucket"
        //prefix that will be added to all resources created in AWS
        prefix = "dev"

        //directory against which @StaticGet annotated files are resolved
        workDirectory = file("src/main/static")

        terraform {
            profile = "example-profile"
            region = "us-east-1"
        }
    }
    //webapp for this gradle project
    webapp {
        //configuration of lambda created
        lambda {
            memoryMb = 1024
            timeoutSec = 120
        }

        //packages in which kotless should search for code
        packages = setOf("org.example.kotless")
        //route53 alias for deployed application
        route53 = Route53("kotless", "example.org")
    }
}

Writing dynamic route

Let's write your first dynamic route.

In Kotless terminology, "dynamic route" is an HTTP route processed by a lambda. On the contrary, "static route" is an HTTP route mapped to an S3 object.

Creating dynamic route is relatively simple. This code snippet will create a route at HTTP path /, which will print "Hello world!"

@Get("/")
fun root(): String {
    return "Hello world!"
}

Note that dynamic route function may have parameters. Parameters will be taken from the URL and body (if presented) and deserialized into the parameters of function. Moreover, the result of function will also be serialized to HTTP response automatically.

In case you need a full control of the HTTP response you may return HttpResponse object, which will be passed to ApiGateway without any changes.

Adding statics to your application

Most of the real-world applications contain static resources, e.g. CSS and JS files. Serving static resources with lambdas is a very wasteful spending of resources, so Kotless proposes a solution — static resources mapped directly to S3.

This code snippet will create route at HTTP path /file.css with file example.css

@StaticGet("/file.css", MimeType.CSS)
val exampleCss = File("example.css")

Note that the file will be resolved against workingDir set in Gradle configuration.

Deploying application to AWS

Finally, you need to deploy your Kotless-based application to AWS. Check that fulfilled all the preliminary conditions and execute deploy task in Gradle.

Kotless will download Terraform, generate deployment code, pack lambda, and, at the end, deploy the application to AWS.

As soon as the deployment is completed, your application will start serving requests at the Route53 DNS name you have assigned to it.