Local Development - TelegrmBot API

Overview

This guide covers running the TelegrmBot API directly on your local machine without Docker. This setup is ideal for:

Active development with fast iteration
Debugging with IDE integration
Testing changes without rebuilding Docker images
Learning the codebase architecture

While Docker provides environment consistency, local development offers faster feedback loops and better debugging capabilities.

Prerequisites

Ensure you have the following installed:

Required Software

Java Development Kit

Version: JDK 21 (Eclipse Temurin recommended)Verify:

java -version
# Should show: openjdk version "21.x.x"

Download: Adoptium

Apache Maven

Version: Maven 3.9+Verify:

mvn -version
# Should show: Apache Maven 3.9.x

Download: maven.apache.org

PostgreSQL

Version: PostgreSQL 15+Verify:

psql --version
# Should show: psql (PostgreSQL) 15.x

Download: postgresql.org

Git

Version: Any recent versionVerify:

git --version

Download: git-scm.com

Optional Tools

IntelliJ IDEA (recommended) or Eclipse/VS Code
pgAdmin or DBeaver for database management
Postman or Insomnia for API testing

Database Setup

Install PostgreSQL

macOS
Ubuntu/Debian
Windows

Using Homebrew:

brew install postgresql@15
brew services start postgresql@15

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

Download installer from postgresql.org
Run installer and follow wizard
Set password for postgres user
Ensure PostgreSQL service is running

Create Database

Connect to PostgreSQL

psql -U postgres

Enter the password you set during PostgreSQL installation.

Create the database

CREATE DATABASE telegrmdb;

Create application user (optional but recommended)

CREATE USER telegrm_user WITH PASSWORD 'dev_password';
GRANT ALL PRIVILEGES ON DATABASE telegrmdb TO telegrm_user;

For development, using a dedicated user is good practice. For simplicity, you can also use the postgres superuser.

Verify database creation

\l

You should see telegrmdb in the list of databases.Exit psql:

\q

Configure Database Connection

Test the connection:

psql -U postgres -d telegrmdb -c "SELECT version();"

If you created a dedicated user, test with:

psql -U telegrm_user -d telegrmdb -c "SELECT version();"

Project Setup

Clone Repository

git clone <repository-url>
cd telegrm

Configure Environment Variables

Copy example environment file

cp .env.example .env

Edit environment variables

Open .env and configure for local development:

# Database - Local PostgreSQL
DB_USER=postgres
DB_PASSWORD=your_postgres_password
DB_URL=jdbc:postgresql://localhost:5432/telegrmdb

# Telegram Bot
TELEGRAM_BOT_TOKEN=your_telegram_bot_token

# AI (OpenRouter)
OPENROUTE_KEY=your_openrouter_api_key
AI_SYSTEM_PROMPT="Eres una IA demente..."
AI_TEMPERATURE=1.4
AI_MAX_TOKENS=200

# Security
JWT_SECRET=your_development_jwt_secret_key

The DB_URL must use localhost for local development, not db (which is for Docker).

Verify Configuration

Ensure Spring Boot can read the .env file. The application.yaml includes:

spring:
  config:
    import: "optional:file:.env[.properties]"

This automatically loads environment variables from .env on startup.

Build and Run

Maven Build

Clean and compile

mvn clean compile

This downloads dependencies and compiles the source code.

Run tests (optional)

mvn test

Tests use Testcontainers, which requires Docker. If Docker isn’t available, skip tests with -DskipTests.

Package application

mvn clean package -DskipTests

This creates an executable JAR in target/telegrm-0.0.1-SNAPSHOT.jar.

Run Application

Maven Spring Boot Plugin
Java JAR
With Profile

Recommended for development - Supports hot reload:

mvn spring-boot:run

This method enables Spring Boot DevTools for automatic restarts when code changes.

Run the packaged JAR directly:

java -jar target/telegrm-0.0.1-SNAPSHOT.jar

With custom JVM options:

java -Xmx512m -Xms256m -jar target/telegrm-0.0.1-SNAPSHOT.jar

Run with a specific Spring profile:

mvn spring-boot:run -Dspring-boot.run.profiles=dev

Or with JAR:

java -jar target/telegrm-0.0.1-SNAPSHOT.jar --spring.profiles.active=dev

Verify Application Started

Successful startup shows:

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::               (v3.5.10)

INFO : Starting TelegrmApplication
INFO : Flyway successfully migrated database
INFO : Started TelegrmApplication in 3.542 seconds

Test the application:

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

Expected response:

{"status":"UP"}

The Telegram bot will automatically start polling for messages. Send a message to your bot to test the integration.

IDE Setup

IntelliJ IDEA

Import project

Open IntelliJ IDEA
Select File → Open
Navigate to project directory and select pom.xml
Choose Open as Project
IntelliJ will automatically import Maven dependencies

Configure JDK

Go to File → Project Structure → Project
Set SDK to Java 21
Set Language level to 21

Enable annotation processing

Required for Lombok:

Go to Settings → Build, Execution, Deployment → Compiler → Annotation Processors
Check Enable annotation processing
Click Apply

Install Lombok plugin

Go to Settings → Plugins
Search for Lombok
Install and restart IntelliJ

Create run configuration

Click Run → Edit Configurations
Click + and select Spring Boot
Name: TelegrmApplication
Main class: com.acamus.telegrm.TelegrmApplication
Environment variables: Load from .env or set manually
Click OK

Run application

Click the green play button or press Shift + F10

IntelliJ IDEA Ultimate includes advanced Spring Boot support with:

Spring Boot dashboard
Endpoint mappings view
Database tools
HTTP client

VS Code

Install extensions

Install the following extensions:

Extension Pack for Java (Microsoft)
Spring Boot Extension Pack (VMware)
Lombok Annotations Support

Open project

code .

VS Code will detect the Maven project and import it.

Configure environment

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "java",
      "name": "Spring Boot-TelegrmApplication",
      "request": "launch",
      "cwd": "${workspaceFolder}",
      "mainClass": "com.acamus.telegrm.TelegrmApplication",
      "projectName": "telegrm",
      "args": "",
      "envFile": "${workspaceFolder}/.env"
    }
  ]
}

Run application

Press F5 or click Run → Start Debugging

Eclipse

Import Maven project

File → Import → Maven → Existing Maven Projects
Browse to project directory
Select pom.xml
Click Finish

Configure JDK

Right-click project → Properties
Java Build Path → Libraries
Ensure JDK 21 is configured

Install Lombok

Download lombok.jar from projectlombok.org
Run: java -jar lombok.jar
Install into Eclipse
Restart Eclipse

Run as Spring Boot App

Right-click project → Run As → Spring Boot App

Development Workflow

Hot Reload with Spring Boot DevTools

The project includes Spring Boot DevTools for automatic restarts:

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

How it works:

Make code changes
Save files (or build in IDE)
Application automatically restarts

DevTools only restarts the application context, not the JVM, making restarts much faster than full restarts.

Database Migrations

The project uses Flyway for database migrations. Migration scripts are in:

src/main/resources/db/migration/

Running migrations: Migrations run automatically on application startup. To run manually:

mvn flyway:migrate

Creating new migrations:

Create a new SQL file following the naming convention:
```
V{version}__{description}.sql
```
Example: V003__add_user_roles_table.sql
Place in src/main/resources/db/migration/
Restart application - Flyway will apply the migration

Never modify existing migration files after they’ve been applied. Create new migrations instead.

Testing

mvn test

Integration tests use Testcontainers, which requires Docker. Ensure Docker is running when executing tests.

Debugging

IntelliJ IDEA
VS Code
Remote Debug

Set breakpoints by clicking left margin
Click debug icon (bug) or press Shift + F9
Use debug controls to step through code

Start application with debug port:

java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 \
     -jar target/telegrm-0.0.1-SNAPSHOT.jar

Then connect your IDE to localhost:5005

Accessing the Application

API Endpoints

Swagger UI

URL: http://localhost:8080/swagger-ui.htmlInteractive API documentation and testing interface

OpenAPI Spec

URL: http://localhost:8080/v3/api-docsRaw OpenAPI 3.0 specification in JSON format

Health Check

URL: http://localhost:8080/actuator/healthApplication health status

Metrics

URL: http://localhost:8080/actuator/metricsApplication metrics and monitoring data

Database Access

Connect to PostgreSQL:

psql -U postgres -d telegrmdb

Common queries:

\dt

Troubleshooting

Port Already in Use

Error:

Web server failed to start. Port 8080 was already in use.

Solutions:

Find and Kill Process
Use Different Port

# Find process using port 8080
lsof -ti:8080

# Kill the process
kill -9 $(lsof -ti:8080)

Add to .env:

SERVER_PORT=8081

Or run with:

mvn spring-boot:run -Dspring-boot.run.arguments="--server.port=8081"

Database Connection Failed

Error:

Connection to localhost:5432 refused

Solutions:

Verify PostgreSQL is running

pg_isready -h localhost -p 5432

Start PostgreSQL service

brew services start postgresql@15

Check database exists

psql -U postgres -l | grep telegrmdb

Verify credentials in .env

Ensure DB_USER, DB_PASSWORD, and DB_URL are correct

Lombok Not Working

Error:

Cannot resolve symbol 'log'
Cannot resolve method 'builder'

Solution:

Ensure Lombok plugin is installed in IDE
Enable annotation processing (IntelliJ/Eclipse)
Rebuild project: mvn clean compile
Restart IDE

Maven Dependency Issues

Error:

Could not resolve dependencies

Solutions:

# Clear Maven cache and re-download
mvn dependency:purge-local-repository

# Force update
mvn clean install -U

# Check for conflicts
mvn dependency:tree

Flyway Migration Failed

Error:

Flyway migration failed: SQL statement invalid

Solutions:

Check migration syntax in SQL files
Clean database (development only):
```
mvn flyway:clean
mvn flyway:migrate
```
Manual repair:
```
mvn flyway:repair
```

flyway:clean drops all database objects. Never use in production!

Next Steps

Architecture Guide

Understand the hexagonal architecture

API Reference

Explore available endpoints

Docker Deployment

Deploy with containers

Development Guide

Learn about the development workflow

Get Started

Architecture

Guides

Deployment

​Overview

​Prerequisites

​Required Software

Java Development Kit

Apache Maven

PostgreSQL

Git

​Optional Tools

​Database Setup

​Install PostgreSQL

​Create Database

​Configure Database Connection

​Project Setup

​Clone Repository

​Configure Environment Variables

​Verify Configuration

​Build and Run

​Maven Build

​Run Application

​Verify Application Started

​IDE Setup

​IntelliJ IDEA

​VS Code

​Eclipse

​Development Workflow

​Hot Reload with Spring Boot DevTools

​Database Migrations

​Testing

​Debugging

​Accessing the Application

​API Endpoints

Swagger UI

OpenAPI Spec

Health Check

Metrics

​Database Access

​Troubleshooting

​Port Already in Use

​Database Connection Failed

​Lombok Not Working

​Maven Dependency Issues

​Flyway Migration Failed

​Next Steps

Architecture Guide

API Reference

Docker Deployment

Development Guide

Build docs developers (and LLMs) love

Overview

Prerequisites

Required Software

Optional Tools

Database Setup

Install PostgreSQL

Create Database

Configure Database Connection

Project Setup

Clone Repository

Configure Environment Variables

Verify Configuration

Build and Run

Maven Build

Run Application

Verify Application Started

IDE Setup

IntelliJ IDEA

VS Code

Eclipse

Development Workflow

Hot Reload with Spring Boot DevTools

Database Migrations

Testing

Debugging

Accessing the Application

API Endpoints

Database Access

Troubleshooting

Port Already in Use

Database Connection Failed

Lombok Not Working

Maven Dependency Issues

Flyway Migration Failed

Next Steps