Installation Guide

This guide covers everything you need to install and run TelegrmBot API in both production (Docker) and development (local) environments.

Prerequisites

Required Software

Java Development Kit 21

TelegrmBot API requires JDK 21 or higher.Verify installation:

java -version

Expected output:

openjdk version "21.0.x"

Installation:

sudo apt update
sudo apt install openjdk-21-jdk

We recommend using Eclipse Temurin (formerly AdoptOpenJDK) for best compatibility.

Apache Maven 3.9+

Maven is used for dependency management and building the application.Verify installation:

mvn -version

Expected output:

Apache Maven 3.9.x

Installation:

sudo apt update
sudo apt install maven

Docker & Docker Compose

Required for containerized deployment (recommended) and integration tests.Verify installation:

docker --version
docker-compose --version

Installation:

Linux: Follow Docker’s official installation guide
macOS: Install Docker Desktop for Mac
Windows: Install Docker Desktop for Windows

Ensure Docker Desktop is running before executing Docker commands.

PostgreSQL 15+ (for local development)

Only needed if running the application locally without Docker.Verify installation:

psql --version

Installation:

sudo apt update
sudo apt install postgresql-15 postgresql-contrib
sudo systemctl start postgresql

Optional Tools

Tool	Purpose	Installation
IntelliJ IDEA	Recommended IDE	Download Community Edition
Postman/Bruno	API testing	Bruno or Postman
Git	Version control	`apt install git` / `brew install git`

The project includes a Bruno collection for API testing. Bruno is an open-source alternative to Postman with Git-friendly storage.

Installation Methods

Choose the installation method that fits your needs:

Docker (Recommended)

Best for: Production deployment, quick testing, consistent environmentsPros:

Zero configuration
Automatic database setup
Isolated environment
Fast deployment

Local Development

Best for: Active development, debugging, IDE integrationPros:

Hot reload support
Full debugging capabilities
Direct database access
Faster iteration

Method 1: Docker Installation (Recommended)

Step 1: Clone the Repository

git clone https://github.com/acamus79/TlgrmBot.git
cd TlgrmBot

Step 2: Configure Environment

Create a .env file from the example:

cp .env.example .env

Edit .env with your configuration:

.env

# Database Configuration
DB_USER=postgres
DB_PASSWORD=your_secure_password

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather

# OpenRouter AI Configuration
OPENROUTE_KEY=your_openrouter_api_key
AI_SYSTEM_PROMPT="You are a helpful AI assistant that responds in a friendly manner."
AI_TEMPERATURE=1.0
AI_MAX_TOKENS=200

# JWT Security
JWT_SECRET=generate_with_openssl_rand_base64_32

Security Best Practices:

Use strong, unique passwords for DB_PASSWORD
Generate JWT_SECRET with: openssl rand -base64 32
Never commit .env to version control
Rotate secrets regularly in production

Step 3: Review Docker Configuration

The docker-compose.yml defines two services:

docker-compose.yml

services:
  db:
    image: postgres:15-alpine
    container_name: telegrm-db
    environment:
      POSTGRES_DB: telegrmdb
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER} -d telegrmdb"]
      interval: 5s
      timeout: 5s
      retries: 5

  app:
    build: .
    container_name: telegrm-api
    env_file:
      - .env
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8080:8080"
    environment:
      DB_URL: jdbc:postgresql://db:5432/telegrmdb
      DB_USERNAME: ${DB_USER}
      DB_PASSWORD: ${DB_PASSWORD}
      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}
      OPENROUTE_KEY: ${OPENROUTE_KEY}
      AI_SYSTEM_PROMPT: ${AI_SYSTEM_PROMPT}
      AI_TEMPERATURE: ${AI_TEMPERATURE}
      AI_MAX_TOKENS: ${AI_MAX_TOKENS}
      JWT_SECRET: ${JWT_SECRET}

Step 4: Build and Launch

Start all services:

docker-compose up --build

First Build: Maven downloads dependencies and compiles the application. This takes 2-4 minutes.Subsequent Builds: Much faster as dependencies are cached.

Step 5: Verify Installation

Check Container Status

docker-compose ps

Both containers should show as Up and healthy:

NAME           STATUS
telegrm-db     Up (healthy)
telegrm-api    Up

Verify Database Migration

Check application logs for Flyway migrations:

docker-compose logs app | grep Flyway

You should see:

Successfully applied 2 migrations

Test Application Health

curl http://localhost:8080/actuator/health

Response:

{"status":"UP"}

Access Swagger UI

Open http://localhost:8080/swagger-ui.html in your browser.You should see the interactive API documentation.

Managing Docker Services

# Stop services (preserve data)
docker-compose down

# Stop and remove all data
docker-compose down -v

# View logs
docker-compose logs -f

# View app logs only
docker-compose logs -f app

# Restart services
docker-compose restart

# Rebuild after code changes
docker-compose up --build

Method 2: Local Development Setup

Step 1: Clone Repository

git clone https://github.com/acamus79/TlgrmBot.git
cd TlgrmBot

Step 2: Set Up PostgreSQL Database

Create the database and user:

-- Connect to PostgreSQL
psql -U postgres

-- Create database
CREATE DATABASE telegrmdb;

-- Create user (optional - can use postgres user)
CREATE USER telegrm_user WITH PASSWORD 'your_password';

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE telegrmdb TO telegrm_user;

-- Exit
\q

Step 3: Configure Application

Set environment variables (choose your method):

export DB_URL="jdbc:postgresql://localhost:5432/telegrmdb"
export DB_USER="postgres"
export DB_PASSWORD="your_password"
export TELEGRAM_BOT_TOKEN="your_bot_token"
export OPENROUTE_KEY="your_openrouter_key"
export JWT_SECRET="your_jwt_secret"
export AI_SYSTEM_PROMPT="You are a helpful assistant"
export AI_TEMPERATURE="1.0"
export AI_MAX_TOKENS="150"

For IntelliJ IDEA:

Open Run → Edit Configurations
Select your Spring Boot configuration
Add environment variables in the “Environment variables” field
Use semicolons (;) to separate variables

Step 4: Build the Application

mvn clean install

This will:

Download all dependencies
Compile the source code
Run unit tests
Package the application as a JAR

First build takes 1-2 minutes. Maven caches dependencies for faster subsequent builds.

Step 5: Run the Application

mvn spring-boot:run

You should see:

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/

Started TelegrmApplication in 6.248 seconds

Step 6: Enable Hot Reload (Optional)

Spring Boot DevTools enables automatic restart on code changes. It’s already included in pom.xml:

pom.xml

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-devtools</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>

In IntelliJ IDEA:

Go to Settings → Build, Execution, Deployment → Compiler
Enable “Build project automatically”
Press Ctrl+Shift+A → search for “Registry”
Enable compiler.automake.allow.when.app.running

Now your application will restart automatically when you save changes!

Database Migrations with Flyway

The application uses Flyway for version-controlled database schema management.

Migration Files

Located in src/main/resources/db/migration/:

db/migration/
├── V1__create_users_table.sql
└── V2__create_chat_tables.sql

How Migrations Work

On Application Startup

Flyway automatically:

Checks the current database schema version
Compares it with migration files
Applies any pending migrations in order
Records applied migrations in flyway_schema_history table

Version Control

Migration files follow the naming convention:

V{version}__{description}.sql

Example: V1__create_users_table.sql

Never Modify Applied Migrations

Once a migration is applied to a database, never modify it. Instead, create a new migration file.

Flyway will fail to start if:

A migration file is modified after being applied
Migration files are out of order
A migration contains SQL syntax errors

Configuration

Flyway is configured in application.yaml:

application.yaml

spring:
  flyway:
    enabled: true
    baseline-on-migrate: true

Running Tests

The project includes comprehensive tests using JUnit 5, Mockito, and Testcontainers.

Run All Tests

mvn clean verify

Testcontainers automatically spins up PostgreSQL in Docker for integration tests. Ensure Docker is running!

Run Unit Tests Only

mvn test

Run Specific Test Class

mvn test -Dtest=RegisterUserUseCaseTest

Test Structure

src/test/java/
├── application/usecases/       # Use case tests
├── domain/model/               # Domain model tests
└── infrastructure/adapters/    # Integration tests

Troubleshooting

Port 8080 already in use

Solution 1: Change the port in application.yaml:

server:
  port: 9090

Solution 2: Kill the process using port 8080:

# Linux/macOS
lsof -ti:8080 | xargs kill -9

# Windows
netstat -ano | findstr :8080
taskkill /PID <PID> /F

Database connection refused

Symptoms:

org.postgresql.util.PSQLException: Connection refused

Solutions:

Verify PostgreSQL is running:

# Linux
sudo systemctl status postgresql

# macOS
brew services list

Check connection parameters in environment variables

Test connection manually:

psql -h localhost -U postgres -d telegrmdb

Verify firewall allows port 5432

Flyway migration failures

Symptoms:

FlywayException: Validate failed: Migration checksum mismatch

Solutions:

Development: Drop and recreate the database:

DROP DATABASE telegrmdb;
CREATE DATABASE telegrmdb;

Production: Repair Flyway:
```
mvn flyway:repair
```
Never modify applied migration files

Maven dependency download issues

Symptoms:

Failed to read artifact descriptor

Solutions:

Clear Maven cache:

rm -rf ~/.m2/repository
mvn clean install

Check internet connection
Try a different Maven repository mirror

Telegram bot not responding

Symptoms: Bot doesn’t reply to messagesSolutions:

Check logs for polling errors:

docker-compose logs app | grep -i telegram

Verify TELEGRAM_BOT_TOKEN is correct
Ensure only one instance is running (polling conflict)
Check that you sent /start or any message to the bot first
Verify bot is not blocked by the user

OutOfMemoryError during build

Symptoms:

java.lang.OutOfMemoryError: Java heap space

Solutions:

Increase Maven memory:

export MAVEN_OPTS="-Xmx2048m -XX:MaxPermSize=512m"
mvn clean install

For IntelliJ IDEA: Increase heap size in Help → Edit Custom VM Options

JWT token validation fails

Symptoms:

401 Unauthorized - Invalid token

Solutions:

Ensure JWT_SECRET is at least 32 characters
Generate a proper secret: openssl rand -base64 32
Verify token format: Authorization: Bearer <token>
Check token hasn’t expired (24-hour validity)
Obtain a fresh token via /auth/login

IDE Setup

IntelliJ IDEA (Recommended)

Import Project

File → Open → Select pom.xml
Choose “Open as Project”
Wait for Maven to import dependencies

Install Lombok Plugin

Settings → Plugins
Search for “Lombok”
Install and restart

Enable Annotation Processing

Settings → Build, Execution, Deployment → Compiler → Annotation Processors✅ Enable annotation processing

Configure Run Configuration

Run → Edit Configurations → Add New → Spring Boot
Main class: com.acamus.telegrm.TelegrmApplication
Add environment variables (see Step 3 above)
Set working directory to project root

VS Code

Install Extensions

Required extensions:

Extension Pack for Java
Spring Boot Extension Pack
Lombok Annotations Support

Configure Environment

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "java",
      "name": "TelegrmApplication",
      "request": "launch",
      "mainClass": "com.acamus.telegrm.TelegrmApplication",
      "env": {
        "DB_URL": "jdbc:postgresql://localhost:5432/telegrmdb",
        "DB_USER": "postgres",
        "DB_PASSWORD": "your_password",
        "TELEGRAM_BOT_TOKEN": "your_token",
        "OPENROUTE_KEY": "your_key",
        "JWT_SECRET": "your_secret"
      }
    }
  ]
}

Production Deployment Checklist

Next Steps

Quick Start Guide

Get the bot running and test the API endpoints

API Documentation

Explore available endpoints in Swagger UI at http://localhost:8080/swagger-ui.html

Architecture Deep Dive

Learn about the hexagonal architecture implementation

Configuration Reference

See application.yaml for all configuration options

Additional Resources

Source Code: https://github.com/acamus79/TlgrmBot
Spring Boot Documentation: https://spring.io/projects/spring-boot
Telegram Bot API: https://core.telegram.org/bots/api
OpenRouter Documentation: https://openrouter.ai/docs
Flyway Documentation: https://flywaydb.org/documentation

Get Started

Architecture

Guides

Deployment

​Installation Guide

​Prerequisites

​Required Software

​Optional Tools

​Installation Methods

Docker (Recommended)

Local Development

​Method 1: Docker Installation (Recommended)

​Step 1: Clone the Repository

​Step 2: Configure Environment

​Step 3: Review Docker Configuration

​Step 4: Build and Launch

​Step 5: Verify Installation

​Managing Docker Services

​Method 2: Local Development Setup

​Step 1: Clone Repository

​Step 2: Set Up PostgreSQL Database

​Step 3: Configure Application

​Step 4: Build the Application

​Step 5: Run the Application

​Step 6: Enable Hot Reload (Optional)

​Database Migrations with Flyway

​Migration Files

​How Migrations Work

​Configuration

​Running Tests

​Run All Tests

​Run Unit Tests Only

​Run Specific Test Class

​Test Structure

​Troubleshooting

​IDE Setup

​IntelliJ IDEA (Recommended)

​VS Code

​Production Deployment Checklist

​Next Steps

Quick Start Guide

API Documentation

Architecture Deep Dive

Configuration Reference

​Additional Resources

Build docs developers (and LLMs) love

Installation Guide

Prerequisites

Required Software

Optional Tools

Installation Methods

Method 1: Docker Installation (Recommended)

Step 1: Clone the Repository

Step 2: Configure Environment

Step 3: Review Docker Configuration

Step 4: Build and Launch

Step 5: Verify Installation

Managing Docker Services

Method 2: Local Development Setup

Step 1: Clone Repository

Step 2: Set Up PostgreSQL Database

Step 3: Configure Application

Step 4: Build the Application

Step 5: Run the Application

Step 6: Enable Hot Reload (Optional)

Database Migrations with Flyway

Migration Files

How Migrations Work

Configuration

Running Tests

Run All Tests

Run Unit Tests Only

Run Specific Test Class

Test Structure

Troubleshooting

IDE Setup

IntelliJ IDEA (Recommended)

VS Code

Production Deployment Checklist

Next Steps

Additional Resources