KtorBase

A template for a Kotlin fullstack web application.

Features

• Docker
  • Dockerfile
• AWS ECS Fargate Deployment via CloudFormation
  • ktorbase.yml
• AWS Container Insights Prometheus Metrics Monitoring
  • jmx-exporter.yml
  • start.sh
• GitHub Actions CI/CD
  • .github/workflows
• Ktor OneLogin SAML Integration
• Typesafe Config
  • application.conf
• Atlaskit Frontend Widgets

You can still use this template perfectly fine if you don't want any of these - just remove the corresponding parts after project generation.

See also official Kotlin Fullstack Sample.

Usage

Generate a new project

On-the-fly & interactive initialization

Download and execute the script init.sh:

bash <(curl -s https://raw.githubusercontent.com/linked-planet/ktorbase/master/init.sh)

The script will prompt for the required parameters.

Clone-based generation

Clone the repository and use the script generate.sh:

# <destination-folder> <group-id> <artifact-id>
./generate.sh ~/tmp com.linked-planet example-project

Update an existing project

If you want to update an existing ktorbase-based project, simply download and run the script update.sh:

bash <(curl -s https://raw.githubusercontent.com/linked-planet/ktorbase/master/update.sh)

The script will prompt for the required parameters.

Running

Note: This template can be run directly, which is useful to try it or to test changes.
The following commands work the same regardless.

via Gradle

export APPLICATION_SECRET=0000000000000000000000000000000
./gradlew -t -Dio.ktor.development=true backend:run

./gradlew -t frontend:browserDevelopmentRun

Important: Make sure to create your own APPLICATION_SECRET for deployments. It is used to encrypt the data stored within the session cookie.

To access the application:

• http://localhost:9090 (backend)
• http://localhost:8080 (frontend)

via IntelliJ

Two run configurations are available automatically after the project is imported:

• backend:run
• frontend:run

Make sure to delegate IntelliJ build and run to Gradle via the IntelliJ settings.

Overview

The generated project consists of:

• A frontend based on React
• A backend based on ktor
• A common module containing shared code

Gradle is used to manage the build for both backend and frontend, as is standard in Kotlin projects.

Backend

The initial HTML is delivered to the client via the IndexRoute. This will cause the client to load the JavaScript frontend application, which is bundled by the Gradle build into the single file frontend-BUILD_VERSION.js.

Note: The BUILD_VERSION is appended to the file name to force Browsers to download the latest JavaScript code after a redeployment, making sure that there is no outdated JavaScript code on clients.

From there, the client can login / logout via the endpoints declared in SessionRoute.

Configuration is done via application.conf (see Typesafe Config).

There is also a mechanism to send configuration to the frontend application, whereby the config data is sent as part of the JSON response of SessionRoute endpoints.

Note that we are using Jetty as ktor engine, because we usually also need SAML Authentication, which introduces this limitation.

Frontend

The frontend shows a simple login form. If you provide credentials admin / admin, the login will succeed, causing the form to disappear, and the main page content to be displayed.

If you refresh the page after successful login, you will still be logged in, as the generated backend is fully configured for session cookie-based authentication.

To render widgets, the Atlaskit frontend components library is used. Of course, you can replace these if you want to use something else.

The build is configured to use Sassy CSS.
(see Sass vs. SCSS: which syntax is better?)

For further information regarding frontend development, see linked-planet UI-Kit.

Deployment

Overview

GitHub Actions is used to build a Docker image and deploy the application on AWS Elastic Container Service via AWS CloudFormation.

• If you don't use GitHub Actions, delete .github
• If you don't use AWS (or you don't want to use our template), delete the aws folder
• If you don't use Docker either, delete the docker-build directory and the Dockerfile

Configuration

AWS configuration parameters are stored within the repository in JSON files per environment (see ktorbase-test.json).

These variables are passed as parameter values for the cloud formation template via script to the AWS CLI (see deploy.sh).

Some of these variables directly affect the resources created by CloudFormation, others are picked up by the application. Those that are relevant for the application will be passed as environment variables into the Docker container, such that they will then be picked up by application.conf.

Try it

We are also publishing the Docker image for the template itself:
Docker Hub - linkedplanet/ktorbase

docker run -it \
  -p 9090:9090 \
  -e APPLICATION_SECRET=0000000000000000000000000000000 \
  linkedplanet/ktorbase:latest

Important: Make sure to create your own APPLICATION_SECRET for deployments. It is used to encrypt the data stored within the session cookie.

Template License

Written in 2020-2022 by linked-planet GmbH.

To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to this template to the public domain worldwide. This template is distributed without any warranty. See http://creativecommons.org/publicdomain/zero/1.0/.