KotlinLinguaBot

Telegram is a bot for learning vocabulary through interactive multiple choice quizzes and tracking statistics using the official Telegram API.

Start

1. Clone the repository

git clone git@github.com:fedorovaea18/KotlinLinguaBot.git
cd KotlinLinguaBot

2. Build the project and create shadow JAR. This will create build/libs/KotlinLinguaBot-1.0-SNAPSHOT-all.jar
3. Prepare dictionary file (optional). The bot can work without words.txt - you can upload words via Telegram later.
   However, if you want to start with a dictionary, create a words.txt file in the project root with the following format: original word|translation

Usage

Telegram Bot

1. Get your bot token from @BotFather
2. Run the bot:

java -jar build/libs/KotlinLinguaBot-1.0-SNAPSHOT-all.jar YOUR_BOT_TOKEN

3. Start chatting with your bot on Telegram
4. Send /start to see the menu

Deploy to VPS

1. Create a Virtual Server(Ubuntu), get the IP address and password for the root user
2. Server Setup:

# Connect to server
ssh root@YOUR_IP_ADDRESS

# Update packages
apt update && apt upgrade -y

# Install Java 21
apt install openjdk-21-jdk -y

# Verify installation
java --version

Deploy Application

# From your local machine, copy files to server
scp build/libs/KotlinLinguaBot-1.0-SNAPSHOT-all.jar root@YOUR_IP_ADDRESS:/root/bot.jar
scp words.txt root@YOUR_IP_ADDRESS:/root/words.txt  # optional

# Connect to server and run bot
ssh root@YOUR_IP_ADDRESS
cd /root
nohup java -jar bot.jar YOUR_BOT_TOKEN &

Configuration

Learning options

By default, a word is considered "learned" after 3 correct answers. You can change this in DatabaseUserDictionary.kt:

class DatabaseUserDictionary(
    private val connection: Connection, 
    private val learningThreshold: Int = 3  // Change this value
)

Question options

Default is 4 answer options. Change in LearnWordsTrainer.kt:

class LearnWordsTrainer(
    private val fileUserDictionary: IUserDictionary,
    private val countOfQuestionWords: Int = 4  // Change this value
)

Automated Deployment with GitHub Actions

The repository includes GitHub Actions workflow for automatic deployment.
To enable it you need to add secrets in GitHub: Settings → Secrets and variables → Actions

HOST: Your VPS IP address
SSH_USER: root
SSH_PASSWORD: VPS root password

Configuration file: .github/workflows/build_and_publish.yml

Technology stack

• API: Telegram Bot API;
• Serialization: Kotlinx Serialization JSON;
• Database: SQLite;
• Testing: JUnit5.