Deploying a Kotlin Application on VPS: A Step-by-Step Guide from A to Z

Introduction: Why Deploying a Kotlin Application Requires a Special Approach

Developing in Kotlin is only half the battle. The other half is competently deploying your application on a remote server. Without this stage, your code will remain just a local project, inaccessible to users.

In this guide, we will cover the full deployment cycle of a Kotlin application on a VPS (Virtual Private Server). You will learn how to build the project into an executable JAR file, configure the server environment, run the application as a service, and ensure its stable operation. The article is intended for developers who already have basic knowledge of Kotlin and Linux.

1. Project Preparation and Building the JAR File

Before uploading the code to the server, you need to build the application into a single artifact. For Kotlin projects written using Spring Boot or Ktor, the standard format is a JAR file (Java Archive).

1.1. Configuring build.gradle.kts

Make sure your build.gradle.kts file contains the plugin for building an executable JAR. For Spring Boot, it looks like this:

plugins {\n    kotlin("jvm") version "1.9.22"\n    id("org.springframework.boot") version "3.2.2"\n    id("io.spring.dependency-management") version "1.1.4"\n}\n\ndependencies {\n    implementation("org.springframework.boot:spring-boot-starter-web")\n    implementation("com.fasterxml.jackson.module:jackson-module-kotlin")\n}\n

For pure Ktor (without Spring), use the application plugin:

plugins {\n    kotlin("jvm") version "1.9.22"\n    application\n}\n\napplication {\n    mainClass.set("com.example.ApplicationKt")\n}\n

1.2. Building the Project

Run the build command in the project root folder:

./gradlew clean build

After a successful build, the file app-0.0.1-SNAPSHOT.jar (the name depends on the configuration) will appear in the build/libs/ directory. Copy it to your local computer.

2. Configuring the VPS Server

For deployment, we will need a VPS with Ubuntu 22.04 LTS installed. It is assumed that you have SSH access and superuser (sudo) privileges.

2.1. Installing Java (JRE)

Kotlin compiles to JVM bytecode, so the server must have Java Runtime Environment (JRE) version 17 or higher installed:

sudo apt update\nsudo apt install openjdk-17-jre -y\njava -version

2.2. Creating a User for the Application

For security reasons, it is not recommended to run the application as root. Let's create a separate user:

sudo useradd -m -s /bin/bash kotlinapp\nsudo passwd kotlinapp

2.3. Uploading the JAR File to the Server

Use SCP to copy the file from your local machine to the VPS:

scp build/libs/app-0.0.1-SNAPSHOT.jar kotlinapp@your-server-ip:/home/kotlinapp/app.jar

3. Running the Application and Configuring Systemd

To ensure the application starts automatically on system boot and does not crash when the SSH connection is lost, we will set it up as a Systemd service.

3.1. Manual Launch (for Testing)

Connect to the server as the kotlinapp user and run:

cd /home/kotlinapp\njava -jar app.jar

If the application starts and responds on port 8080, proceed to the next step. Stop the process (Ctrl+C).

3.2. Creating a Systemd Unit File

Create the service file:

sudo nano /etc/systemd/system/kotlin-app.service

Paste the following content:

[Unit]\nDescription=Kotlin Application Service\nAfter=net